Package ptolemy.actor.lib.fmi

Class FMUImport

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Advanceable, ContinuousStatefulComponent, ContinuousStepSizeController, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    FMUImportHybrid, FMUQSS
    public class FMUImport
extends TypedAtomicActor
implements Advanceable, ContinuousStepSizeController, ContinuousStatefulComponent
    Invoke a Functional Mock-up Interface (FMI) Functional Mock-up Unit (FMU).

    Read in a .fmu file named by the fmuFile parameter. The .fmu file is a zipped file that contains a file named modelDescription.xml 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 .fmu file.

    To use this actor from within Vergil, use File -> Import -> Import FMU, which will prompt for a .fmu file. This actor is not 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.

    FMI documentation may be found at http://www.modelisar.com/fmi.html.

    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 isStepSizeAccurate(), 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 rollBackToCommittedState(). 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).

    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. This may not be a good assumption, so it issues a warning.

    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 t depends on the input at time t. It is irrelevant whether it depends on the input at earlier times.

    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.

    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.

    Since:
    Ptolemy II 10.0
    Version:
    $Id$
    Author:
    Christopher Brooks, Michael Wetter, Edward A. Lee
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Red (cxh)

    • Field Detail

      • fmiVersion

        public StringParameter fmiVersion
        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.

      • fmuFile

        public FileParameter fmuFile
        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".

      • modelExchange

        public Parameter modelExchange
        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.

      • removeDirectDependency

        public Parameter removeDirectDependency
        If true, then this, then the dependency of all inputs on outputs are removed. This is particularly useful for FMI 1.0 which do not declare any input/output dependency forcing to add microstep delays to the system even when not needed.

      • stateVariablesAsInputPorts

        public Parameter stateVariablesAsInputPorts
        If true, then this FMU has state variables that are visible as Ptolemy input ports. This is a boolean that defaults to true. Importing an FMU for use with QSS would set this to parameter to false, which indicates that the state variables are output ports. This parameter is set to expert mode because normally a user should not be allowed to change it.

      • persistentInputs

        public Parameter persistentInputs
        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.

      • suppressWarnings

        public Parameter suppressWarnings
        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.

      • useRawJNI

        public Parameter useRawJNI
        If true, then use raw JNI instead of using JNA, which in turn uses JNI. Raw JNI is faster than JNA, but raw JNI only supports FMI-2.0 Model Exchange and Real values. The default value is false, meaning that JNA is used.

      • visible

        public Parameter visible
        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.

      • _callbacks

        protected FMICallbackFunctions _callbacks
        FMI-1.0 callback functions provided to the C code as a struct. This reference is non-null between creation of the struct in preinitialize() and invocation of wrapup() so that the callback structure does not get garbage collected. JNA documentation is silent about whether there is any assurance a C pointer to this struct is valid until garbage collection, but we assume it is.

      • _callbacks20

        protected FMI20CallbackFunctions _callbacks20
        FMI-2.0 callback functions provided to the C code as a struct. This reference is non-null between creation of the struct in preinitialize() and invocation of wrapup() so that the callback structure does not get garbage collected. JNA documentation is silent about whether there is any assurance a C pointer to this struct is valid until garbage collection, but we assume it is.

      • _eventInfoJNI

        protected FMI20EventInfo _eventInfoJNI
        The eventInfo.

      • _fmiComponent

        protected com.sun.jna.Pointer _fmiComponent
        The FMI component created by the modelIdentifier_fmiInstantiateSlave() method.

      • _fmiJNIComponent

        protected int _fmiJNIComponent
        The index of the component. Only used when using JNI directly.

      • _fmiModelDescription

        protected FMIModelDescription _fmiModelDescription
        A representation of the fmiModelDescription element of a Functional Mock-up Unit (FMU) file.

      • _fmiVersion

        protected double _fmiVersion
        The version of FMI that the FMU declares it is compatible with, converted to a double for easy comparison.

      • _threshold

        protected double _threshold
        The delta to exceed to produce outputs if QSS is used.

      • _states

        protected java.nio.DoubleBuffer _states
        For model exchange, the FMU state variables.

      • _fmiNewDiscreteStatesFunction

        protected com.sun.jna.Function _fmiNewDiscreteStatesFunction
        The _fmi2NewDiscreteStates function, present only in FMI-2.0.

      • _fmiEnterContinuousTimeModeFunction

        protected com.sun.jna.Function _fmiEnterContinuousTimeModeFunction
        The fmiEnterContinuousTimeMode Function, present only in FMI-2.0.

      • _fmiCompletedIntegratorStepFunction

        protected com.sun.jna.Function _fmiCompletedIntegratorStepFunction
        The fmiCompletedIntegratorStep() function.

      • _fmiSetTimeFunction

        protected com.sun.jna.Function _fmiSetTimeFunction
        Function to set the time of the FMU for model exchange.

      • _fmiGetDerivativesFunction

        protected com.sun.jna.Function _fmiGetDerivativesFunction
        Function to get the derivatives of a model-exchange FMU.

      • _fmiGetContinuousStatesFunction

        protected com.sun.jna.Function _fmiGetContinuousStatesFunction
        Function to get the continuous states of the FMU for model exchange.

      • _fmiGetDirectionalDerivativeFunction

        protected com.sun.jna.Function _fmiGetDirectionalDerivativeFunction
        Function to get the directional derivatives of a model-exchange FMU.

      • _fmiGetEventIndicatorsFunction

        protected com.sun.jna.Function _fmiGetEventIndicatorsFunction
        Function to get the event indicators of the FMU for model exchange.

      • _firstFire

        protected boolean _firstFire
        Flag identifying the first invocation of fire() after initialize.

      • _firstFireInIteration

        protected boolean _firstFireInIteration
        Flag identifying the first invocation of fire() after each invocation of initialize() or postfire().

      • _fmiGetRealStatusFunction

        protected com.sun.jna.Function _fmiGetRealStatusFunction
        The fmiGetRealStatus() function.

      • _fmiGetIntegerStatusFunction

        protected com.sun.jna.Function _fmiGetIntegerStatusFunction
        The fmiGetIntegerStatus() function.

      • _fmiDoStepFunction

        protected com.sun.jna.Function _fmiDoStepFunction
        The fmiDoStep() function.

      • _fmiEnterInitializationModeFunction

        protected com.sun.jna.Function _fmiEnterInitializationModeFunction
        The fmiEnterInitializationModeFunction, present only in FMI-2.0.

      • _fmiExitInitializationModeFunction

        protected com.sun.jna.Function _fmiExitInitializationModeFunction
        The fmiExitInitializationModeFunction, present only in FMI-2.0.

      • _fmiSetupExperimentFunction

        protected com.sun.jna.Function _fmiSetupExperimentFunction
        The _fmiSetupExperiment function.

      • _lastCommitTime

        protected Time _lastCommitTime
        The time at which the last commit occurred (initialize or postfire).

      • _lastFireTime

        protected Time _lastFireTime
        The time at which the last fire occurred.

      • _lastFireMicrostep

        protected int _lastFireMicrostep
        The microstep at which the last fire occurred.

      • _modelInitialized

        protected boolean _modelInitialized
        True if _fmiInitialize() completed.

      • _newStates

        protected double[] _newStates
        The new states computed in fire(), to be committed in postfire.

      • _relativeTolerance

        protected double _relativeTolerance
        The relative tolerance for errors in double values.

      • _refinedStepSize

        protected double _refinedStepSize
        Refined step size suggested by the FMU if doStep failed, or -1.0 if there is no suggestion.

      • _stepSizeRejected

        protected boolean _stepSizeRejected
        Indicator that the proposed step size provided to the fire method has been rejected by the FMU.

      • _isStrict

        protected boolean _isStrict
        Indicator of whether the actor is strict, meaning that all inputs must be known to fire it.

      • _suggestZeroStepSize

        protected boolean _suggestZeroStepSize
        Indicator that we have had iteration with a rejected step size, so the next suggested step size should be zero.

      • _toleranceControlled

        protected byte _toleranceControlled
        Boolean indicating whether the director uses an error tolerance.

    • Method Detail

      • advance

        public boolean advance​(Time time,
                       int microstep)
                throws IllegalActionException
        Advance to the specified time.
        Specified by:
        advance in interface Advanceable
        Parameters:
        time - The time to advance.
        microstep - The microstep to advance.
        Returns:
        True if advancement to the specified time succeeds.
        Throws:
        IllegalActionException - If an error occurs advancing time.

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        If the specified attribute is fmuFile, then unzip the file and load in the .xml file, creating and deleting parameters as necessary.
        Overrides:
        attributeChanged in class NamedObj
        Parameters:
        attribute - The attribute that has changed.
        Throws:
        IllegalActionException - If the specified attribute is fmuFile and the file cannot be opened or there is a problem creating or destroying the parameters listed in the file.

      • fire

        public void fire()
          throws IllegalActionException
        Invoke fmiDoStep() of the slave FMU, if necessary to catch up to current time, and then set the (known) inputs of the FMU and retrieve and send out any outputs for which all inputs on which the output depends are known.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class AtomicActor<TypedIOPort>
        Throws:
        IllegalActionException - If the FMU indicates a failure.

      • getInputDependencyList

        public java.util.List<FMIScalarVariable> getInputDependencyList​(FMIScalarVariable scalar)
        Return the input scalar dependency for a given FMI scalar.
        Parameters:
        scalar - The FMI scalar output port for which you want the FMI input scalar dependency list.
        Returns:
        the list of input ports that directly influence the value of the given output port. If port is not an output port return null.

      • getScalarVariables

        public java.util.List<FMIScalarVariable> getScalarVariables()
        Return the list of all the scalar variables defined in the FMU interface.
        Returns:
        the list of ScalarVariables

      • importFMU

        public static void importFMU​(java.lang.Object originator,
                             FileParameter fmuFileParameter,
                             NamedObj context,
                             double x,
                             double y,
                             boolean modelExchange)
                      throws IllegalActionException,
                             java.io.IOException
        Import a FMUFile.
        Parameters:
        originator - The originator of the change request.
        fmuFileParameter - The .fmuFile
        context - The context in which the FMU actor is created.
        x - The x-axis value of the actor to be created.
        y - The y-axis value of the actor to be created.
        modelExchange - True if the FMU should be imported as a model exchange FMU.
        Throws:
        IllegalActionException - If there is a problem instantiating the actor.
        java.io.IOException - If there is a problem parsing the fmu file.

      • initialize

        public void initialize()
                throws IllegalActionException
        Initialize this FMU wrapper. For co-simulation, this initializes the FMU. For model exchange, it does not, because for model exchange, the inputs at the start time need to be provided prior to initialization. Initialization will therefore occur in the first invocation of fire().
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class AtomicActor<TypedIOPort>
        Throws:
        IllegalActionException - If the slave FMU cannot be initialized.

      • isStepSizeAccurate

        public boolean isStepSizeAccurate()
        Return whether the most recent call to fmiDoStep() succeeded. This will return false if fmiDoStep() discarded the step. This method assumes that if a director calls this method, then it will fully handle the discarded step. If this method is not called, then the next call to postfire() will throw an exception.
        Specified by:
        isStepSizeAccurate in interface ContinuousStepSizeController
        Returns:
        True if the current step is accurate.

      • isStrict

        public boolean isStrict()
        Return false if any output has been found that not depend directly on an input.
        Specified by:
        isStrict in interface Executable
        Overrides:
        isStrict in class AtomicActor<TypedIOPort>
        Returns:
        False if this actor can be fired without all inputs being known.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Override the base class to record the current time as the last commit time.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class AtomicActor<TypedIOPort>
        Returns:
        True if execution can continue into the next iteration.
        Throws:
        IllegalActionException - If the step size was rejected, if thrown while requesting refiring if necessary, if thrown while the FMU state is being recorded or if thrown by the superclass.

      • runNativeFMU

        public static int runNativeFMU​(int idx,
                               int fla,
                               java.lang.String instance,
                               java.lang.String jniResourceLocation,
                               java.lang.String fmuResourceLocation,
                               double tStart,
                               double tEnd,
                               double time,
                               int toleranceDefined,
                               double tolerance,
                               int visible,
                               int loggingOn,
                               java.lang.String guid,
                               double[] continuousStateDerivatives,
                               double[] continuousStatesFromFMU,
                               double[] continuousStatesToFMU,
                               double[] inputValues,
                               long[] inputValueReferences,
                               double[] outputValues,
                               long[] outputValueReferences,
                               long continuousStateDerivativesValueReference,
                               double[] directionalStateDerivatives,
                               long[] directionalStateDerivativesValueReferences,
                               double[] directionalInputDerivatives,
                               long[] directionalInputDerivativesValueReferences,
                               double[] continuousSecondDerivatives,
                               double[] eventIndicators,
                               double[] nextTimeEvent,
                               double[] stepEvent)
        Interface to the FMU.

        This methods calls the FMU using JNI with different flags. 0: Instantiate. 1: Initialize. 2: Enter event mode. 3: Enter continuous mode. 4: Get continuous states. 5: Get state derivatives. 6: Set continuous states. 7: Set single inputs. 8: Get single outputs. 9: Complete integrator. -1: Terminate simulation. -10: Get directional derivatives."

        Parameters:
        idx - The index of the FMU instance.
        fla - The flag to determine the FMI functions to call.
        instance - The FMU instance name.
        jniResourceLocation - The path to the FMU native library.
        fmuResourceLocation - The path to the FMU resource location.
        tStart - The FMU simulation start time.
        tEnd - the FMU simulation end time.
        time - The current simulation time.
        toleranceDefined - the flag is true if sover tolerance is defined.
        tolerance - The FMU solver tolerance.
        visible - The FMU visible flag.
        loggingOn - The FMU logginOn flag.
        guid - The FMU GUID.
        continuousStateDerivatives - The FMU state derivatives to get.
        continuousStatesFromFMU - The FMU continuous states to get.
        continuousStatesToFMU - The FMU continuous states to set.
        inputValues - The FMU input values.
        inputValueReferences - The FMU input value references.
        outputValues - The FMU output values.
        outputValueReferences - The FMU output value references.
        continuousStateDerivativesValueReference - The FMU state derivative value reference.
        directionalStateDerivatives - The FMU directional state derivatives.
        directionalStateDerivativesValueReferences - The FMU directional state derivatives value references.
        directionalInputDerivatives - The FMU directional input derivatives.
        directionalInputDerivativesValueReferences - The FMU directional input derivatives value references.
        continuousSecondDerivatives - The FMU second derivatives.
        eventIndicators - The FMU event indicators.
        nextTimeEvent - The next FMU time event.
        stepEvent - The step event indicator.
        Returns:
        FMU instance The index when fla is zero.

      • suggestedStepSize

        public double suggestedStepSize()
                         throws IllegalActionException
        Return the suggested next step size. This method returns 0.0 if the previous invocation of fmiDoStep() was discarded, in order to force a zero-time integration step after an event is detected by the FMU. Otherwise, return Double.MAC_VALUE. return java.lang.Double.MAX_VALUE.
        Specified by:
        suggestedStepSize in interface ContinuousStepSizeController
        Returns:
        The suggested next step size.
        Throws:
        IllegalActionException - If an actor suggests an illegal step size.

      • _acceptFMU

        protected static boolean _acceptFMU​(FMIModelDescription fmiModelDescription)
                             throws java.io.IOException
        Determine if the model description is acceptable. For example a derived class that imports FMI-2.0 ME FMUs might throw an exception.
        Parameters:
        fmiModelDescription - The description of the model to be checked.
        Returns:
        true if the model description is acceptable. In this base class, true is always returned.
        Throws:
        java.io.IOException - If the model description is not acceptable.

      • _checkEventIndicators

        protected boolean _checkEventIndicators()
                                 throws IllegalActionException
        Return true if we are not in the first firing and the sign of some event indicator has changed.
        Returns:
        True if a state event has occurred.
        Throws:
        IllegalActionException - If the fmiGetEventIndicators function is missing, or if calling it does not return fmiOK.

      • _enterContinuousTimeMode

        protected void _enterContinuousTimeMode()
                                 throws IllegalActionException
        Invoke the fmi2EnterContinuousTimeMode() function. This method is typically invoked by FMI-2.0 model exchange.
        Throws:
        IllegalActionException - If there is a problem invoking the fmi2ContinuousTimeMode() function in the fmi.

      • _enterEventMode

        protected void _enterEventMode()
                        throws IllegalActionException
        Invoke the fmi2EnterEventMode() function. This method is typically invoked by FMI-2.0 model exchange.
        Throws:
        IllegalActionException - If there is a problem invoking the fmi2EnterEventMode() function in the fmi.

      • _debugToStdOut

        protected void _debugToStdOut​(java.lang.String message)
        Print the debug message to stdout and flush stdout. This is useful for tracking down segfault problems. To use this, right click on the FMUImport actor and select "Listen to Actor". The logging messages will appear on stdout and in the listener window.
        Parameters:
        message - The message to be displayed.

      • _fmiCompletedIntegratorStep

        protected boolean _fmiCompletedIntegratorStep​(boolean eventOccuredOrNoSetFMUStatePriorToCurrentPoint)
                                       throws IllegalActionException
        For model exchange, complete the integrator step.

        Under FMI previous to 2.0, if the FMU indicates that fmiEventUpdate() should be called, call it.

        Note that in FMI-2.0, the ModelExchange attribute as an element FMI20ModelExchangeCapabilities.completedIntegratorStepNotNeeded that in the default is false, which means that fmiCompletedIntegratorStep() should be called. However, if completedIntegratorStepNotNeeded is true, then fmiCompletedIntegratorStep is not called.

        Under FMI-2.0, if the fmi2CompletedIntegrationStep() method sets the value of the terminateSimulation parameter to true, then Director.finish() is invoked.

        Parameters:
        eventOccuredOrNoSetFMUStatePriorToCurrentPoint - For FMI < 2.0, true if event update should be called. for FMI ≥ 2.0, True if fmi2SetFMUState() will not be called for times before the current time in this simulation.
        Returns:
        FMI-2.0 returns true if the call to fmi2CompletedIntegratorStep() sets the value of the enterEventMode parameter to true.
        Throws:
        IllegalActionException - If the FMU does not return fmiOK.

      • _fmiCompletedIntegratorStepJNI

        protected void _fmiCompletedIntegratorStepJNI()
        For model exchange, complete the integrator step.

      • _fmiDoStep

        protected double _fmiDoStep​(Time newTime,
                            int newMicrostep)
                     throws IllegalActionException
        Advance from the last firing time or last commit time to the specified time and microstep by calling fmiDoStep(), if necessary. This method is for co-simulation only. Such an advance is necessary if the newTime is not equal to the last firing time, or if it is equal and the newMicrostep is greater than the last firing microstep. If the step size is rejected, then return a new suggested step size, which is either half the specified step size, or, if the FMU supports it, the last successful time reported by the FMU. As a side effect, if the time advance is successful, then the _lastFireTime and _lastFireMicrostep are updated to match the arguments, indicating that the FMU has advanced to that time.
        Parameters:
        newTime - The time to advance to.
        newMicrostep - The microstep to advance to.
        Returns:
        A revised suggested step size, or -1.0 if the step size was accepted by the FMU.
        Throws:
        IllegalActionException - If fmiDoStep() returns anything other than fmiDiscard or fmiOK.

      • _fmiEnterContinuousTimeModeJNI

        protected void _fmiEnterContinuousTimeModeJNI()
        Enter continuous mode of the FMU array.

      • _fmiEnterEventModeJNI

        protected void _fmiEnterEventModeJNI()
        Enter event mode of the FMU.

      • _fmiGetContinuousStates

        protected void _fmiGetContinuousStates​(double[] values)
                                throws IllegalActionException
        For model exchange, Get the continuous states of the FMU to the specified array.
        Parameters:
        values - The values of the states.
        Throws:
        IllegalActionException - If the length of the array does not match the number of continuous states, or if the FMU does not return fmiOK.

      • _fmiGetContinuousStatesJNI

        protected void _fmiGetContinuousStatesJNI​(double[] values)
        Get the continuous states of the FMU to the specified array.
        Parameters:
        values - The values of the outputs to get.

      • _fmiGetDerivatives

        protected double[] _fmiGetDerivatives()
                               throws IllegalActionException
        Return the derivatives of the continuous states provided by the FMU.
        Returns:
        The derivatives of the FMU.
        Throws:
        IllegalActionException - If the FMU does not return fmiOK.

      • _fmiGetDerivativesJNI

        protected void _fmiGetDerivativesJNI​(double[] values)
        Get the derivatives of the FMU to the specified array.
        Parameters:
        values - The derivative values.

      • _fmiGetEventIndicatorsJNI

        protected void _fmiGetEventIndicatorsJNI​(double[] values)
        Get the event indicators.
        Parameters:
        values - The event indicators values.

      • _fmiGetRealJNI

        protected void _fmiGetRealJNI​(double[] values,
                              long[] valueReferences)
        Get the double inputs of the FMU to the specified array.
        Parameters:
        values - The values of the outputs to get.
        valueReferences - The value references of the outputs.

      • _fmiInitialize

        protected void _fmiInitialize()
                       throws IllegalActionException
        Invoke _fmiInitialize() (for model exchange) or _fmiInitializeSlave() (for co-simulation) on the FMU. In the case of model exchange, this method also checks for a returned next event time and calls fireAt() on the director if a next event time is returned. In the case of co-simulation, if the FMU provides a maximum step size, get that from the FMU and call fireAt() as well.
        Throws:
        IllegalActionException - If the FMU does not return fmiOK.

      • _fmiInitializeJNI

        protected void _fmiInitializeJNI()
        Initialize the FMU array.

      • _fmiInstantiateJNI

        protected java.lang.Integer _fmiInstantiateJNI​(java.lang.String modelIdentifier,
                                               java.lang.String fmuLibPath,
                                               java.lang.String fmuResourceLocation,
                                               double startime,
                                               double stoptime,
                                               double currentime,
                                               java.lang.Integer toleranceDefined,
                                               double quantum,
                                               byte visible,
                                               byte logging,
                                               java.lang.String guid,
                                               double[] derivatives,
                                               double[] eventIndicators)
        Instantiate the FMU array.
        Parameters:
        modelIdentifier - The model identifier of the FMU.
        fmuLibPath - The path to the FMu library.
        fmuResourceLocation - The path to the FMU resource.
        startime - The FMU start time.
        stoptime - The FMU stop time.
        currentime - The FMU current time.
        toleranceDefined - The FMU tolerance defined.
        quantum - The FMU tolerance.
        visible - The FMU visible attribute.
        logging - The FMU logging attribute.
        guid - The FMU GUID.
        derivatives - The FMU first derivatives.
        eventIndicators - The FMU event indicators.
        Returns:
        An integer that specifies the FMU.

      • _fmiNewDiscreteStatesJNI

        protected void _fmiNewDiscreteStatesJNI()
        Enter discrete states of the FMU array.

      • _fmiSetContinuousStates

        protected void _fmiSetContinuousStates​(double[] values)
                                throws IllegalActionException
        For model exchange, set the continuous states of the FMU to the specified array.
        Parameters:
        values - The values to assign to the states.
        Throws:
        IllegalActionException - If the length of the array does not match the number of continuous states, or if the FMU does not return fmiOK.

      • _fmiSetContinuousStatesJNI

        protected void _fmiSetContinuousStatesJNI​(double[] values)
        For model exchange, set the continuous states of the FMU to the specified array.
        Parameters:
        values - The values to assign to the states.

      • _fmiSetRealJNI

        protected void _fmiSetRealJNI​(double[] values,
                              long[] valueReferences)
        Set the double inputs of the FMU to the specified array.
        Parameters:
        values - The values to assign to the inputs.
        valueReferences - The value references of the inputs.

      • _fmiSetTimeJNI

        protected void _fmiSetTimeJNI​(double timeValue)
        Set the time in the FMU.
        Parameters:
        timeValue - The current time

      • _fmiStatusDescription

        protected static java.lang.String _fmiStatusDescription​(int fmiStatus)
        Return a string describing the specified fmiStatus.
        Parameters:
        fmiStatus - The status returned by an FMI procedure.
        Returns:
        a String describing the status.

      • _freeFMUState

        protected void _freeFMUState()
                      throws IllegalActionException
        Free the memory recording FMU state, if the canGetAndSetFMUstate capability flag for the FMU is true. Otherwise, do nothing.
        Throws:
        IllegalActionException - If freeing the memory the state fails.

      • _getInputs

        protected java.util.List<FMUImport.Input> _getInputs()
                                              throws IllegalActionException
        Return a list of inputs of the FMU. An input has both a declared ScalarVariable in the model description file with causality declared to be "input" and a port with the same name contained by this actor. Each returned input contains a reference to the port and a reference to the FMIScalarVariable.
        Returns:
        A list of inputs of the FMU.
        Throws:
        IllegalActionException - If no port matching the name of a variable declared as an input is found.

      • _getOutputs

        protected java.util.List<FMUImport.Output> _getOutputs()
                                                throws IllegalActionException
        Return a list of connected outputs of the FMU. An output has both a declared ScalarVariable in the model description file with causality declared to be "output" and a port with the same name contained by this actor. If the port exists but is not connected to anything (its width is zero), then it this output is not included in the returned list. Each returned output contains a reference to the port, a reference to the FMIScalarVariable, and a set of input port on which the output declares that it depends (or a null if it makes no such dependency declaration).
        Returns:
        A list of outputs of the FMU.
        Throws:
        IllegalActionException - If an expected output is not found, or if the width of the output cannot be determined.

      • _getStepSize

        protected double _getStepSize()
                       throws IllegalActionException
        Return the current step size. If the director implements ContinuousStatefulDirector, then the value returned by currentStepSize() is returned. If the director is an instance of PeriodicDirector, then the value returned by periodValue() is returned.
        Returns:
        the current step size.
        Throws:
        IllegalActionException - If there is a problem getting the currentStepSize.

      • _importFMU

        protected static void _importFMU​(java.lang.Object originator,
                                 FileParameter fmuFileParameter,
                                 NamedObj context,
                                 double x,
                                 double y,
                                 boolean modelExchange,
                                 boolean addMaximumStepSizeParameter,
                                 boolean stateVariablesAsInputPorts,
                                 java.lang.String actorClassName,
                                 java.lang.reflect.Method acceptFMUMethod)
                          throws IllegalActionException,
                                 java.io.IOException
        Import a FMUFile.
        Parameters:
        originator - The originator of the change request.
        fmuFileParameter - The .fmuFile
        context - The context in which the FMU actor is created.
        x - The x-axis value of the actor to be created.
        y - The y-axis value of the actor to be created.
        modelExchange - True if the fmu should be imported as a model exchange fmu.
        addMaximumStepSizeParameter - True if a parameter named "maximumStepSize" should be added.
        stateVariablesAsInputPorts - True if, under state variables in the FMU should be represented as input ports in the Ptolemy actor. Typically, this parameter is true, but for QSS, it would be false, indicating that the state variables are output ports.
        actorClassName - The class name of the Ptolemy actor to be instantiated, for example "ptolemy.actor.lib.fmi.FMUImport".
        acceptFMUMethod - The _acceptFMU(FMIModelDescription) method. Derived classes provide a different method than the parent class.
        Throws:
        IllegalActionException - If there is a problem instantiating the actor.
        java.io.IOException - If there is a problem parsing the fmu file.

      • _isScalarAPtolemyInput

        protected static boolean _isScalarAPtolemyInput​(FMIModelDescription fmiModelDescription,
                                                FMIScalarVariable scalar,
                                                boolean stateVariablesAsInputPorts)
        Return true if scalar is a Ptolemy input. Under FMI-2.0 Model Exchange, a scalar is an input if the scalar has a derivative scalar. Under FMI-1.0 or 2.0, Model Exchange or Co-Simulation, a scalar with causality="input" is also an input
        Parameters:
        fmiModelDescription - The model description.
        scalar - the FMIScalarVariable in question
        stateVariablesAsInputPorts - True if, under state variables in the FMU should be represented as ports in the Ptolemy actor. Typically, this parameter is true, but for QSS, it would be false.
        Returns:
        true if the scalar should be an input.

      • _newDiscreteStatesNeeded

        protected boolean _newDiscreteStatesNeeded​(FMI20EventInfo.ByReference fmi20EventInfo)
                                    throws IllegalActionException
        Invoke newDiscreteStatesNeeded() and return true if the fmu wants to terminate.
        Parameters:
        fmi20EventInfo - A reference to the FMI-2.0 event information.
        Returns:
        true if the fmu wants to terminate.
        Throws:
        IllegalActionException - If there was a failure to set a new discrete state.

      • _recordFMUState

        protected void _recordFMUState()
                        throws IllegalActionException
        Record the current FMU state. For model exchange, this copies the FMU state into the variable _state using fmiGetContinuousStates(). For co-simulation, if the canGetAndSetFMUstate capability flag for the FMU is true, then it record the state by invoking fmiGetFMUstate(). If the capability flag is false, do nothing.
        Throws:
        IllegalActionException - If recording the state fails.

      • _requestRefiringIfNecessary

        protected void _requestRefiringIfNecessary()
                                    throws IllegalActionException
        If the FMU can provide a maximum step size, query for that maximum step size and call fireAt() to ensure that the FMU is invoked at the specified time.
        Throws:
        IllegalActionException - If the call to fireAt() throws it.

      • _restoreFMUState

        protected void _restoreFMUState()
                         throws IllegalActionException
        Restore the current FMU state to match that most recently recorded, if the canGetAndSetFMUstate capability flag for the FMU is true. Otherwise, do nothing.
        Throws:
        IllegalActionException - If there is no recorded state, or if restoring the state fails.

      • _setParameter

        protected void _setParameter​(Parameter parameter,
                             FMIScalarVariable scalar)
                      throws IllegalActionException
        Set a Ptolemy II Parameter to the value of a FMI ScalarVariable.
        Parameters:
        parameter - The Ptolemy parameter to be set.
        scalar - The FMI scalar variable that contains the value to be set
        Throws:
        IllegalActionException - If the scalar is of a type that is not handled.

      • _setFMUScalarVariable

        protected void _setFMUScalarVariable​(FMIScalarVariable scalar,
                                     Token token)
                              throws IllegalActionException
        Set a scalar variable of the FMU to the value of a Ptolemy token.
        Parameters:
        scalar - the FMI scalar to be set.
        token - the Ptolemy token that contains the value to be set.
        Throws:
        IllegalActionException - If the scalar is of a type that is not handled or if the type of the token does not match the type of the scalar.

      • _skipIfKnown

        protected boolean _skipIfKnown()
                        throws IllegalActionException
        Return true if outputs are skipped if known. A true value means that only a single output token will be produced in each iteration of this actor. A false value means that a sequence of output tokens may be produced. Generally, for domains that implement fixed-point semantics, such as Continuous and SR, the return value should be true. Otherwise it should be false. If the director is a ContinuousDirector, then return true. If the director is SDFDirector, then return false.
        Returns:
        the true if outputs that have been set are skipped.
        Throws:
        IllegalActionException - If there is a problem getting the currentStepSize.

      • _updateParameters

        protected void _updateParameters()
                          throws IllegalActionException,
                                 NameDuplicationException
        Update the parameters listed in the modelDescription.xml file contained in the zipped file named by the fmuFile parameter.
        Throws:
        IllegalActionException - If the file named by the fmuFile parameter cannot be unzipped or if there is a problem deleting any pre=existing parameters or creating new parameters.
        NameDuplicationException - If a parameter to be created has the same name as a pre-existing parameter.

      • _completedIntegratorStepNotNeeded

        protected boolean _completedIntegratorStepNotNeeded()
                                             throws IllegalActionException
        Return true if the modelExchangeCapabilities has a completedIntegratorStepNotNeeded flag that is set to true.
        Returns:
        The value of the completedIntegratorStepNotNeeded field. If the modelDescription.xml file does not contain a ModelExchange attribute, then false is returned.
        Throws:
        IllegalActionException - If the modelExchangeCapabilities does not have a completedIntegratorStepNotNeeded field.

      • _checkFmiCommon

        protected void _checkFmiCommon()
                        throws IllegalActionException
        If _fmiModelDescription is null or does not have a non-null modelIdentifier, then thrown an exception with an informative message.
        Throws:
        IllegalActionException - If critical information is missing.

      • _getPortByNameOrDisplayName

        protected Port _getPortByNameOrDisplayName​(java.lang.String portName)
        Get the port by display name or, if the display name is not set, then by name. This is used to handle variable names that have periods (".") in them.
        Parameters:
        portName - The name of the port to find. The name might have a period in it, for example "foo.bar".
        Returns:
        The port or null;

      • _fmiType2PtolemyType

        protected static java.lang.String _fmiType2PtolemyType​(FMIType type)
                                                throws IllegalActionException
        Given a FMIType object, return a string suitable for setting the TypeAttribute.
        Parameters:
        type - The FMIType object.
        Returns:
        a string suitable for ptolemy.actor.TypeAttribute.
        Throws:
        IllegalActionException - If the type is not supported.

      • _hasQSSDirector

        protected boolean _hasQSSDirector()
        Return true if we use the QSSDirector.
        Returns:
        true if we use the QSS Director.

      • _useRawJNI

        protected boolean _useRawJNI()
                      throws IllegalActionException
        Return true if we use use raw JNI instead of JNA.
        Returns:
        true if raw JNI should be used.
        Throws:
        IllegalActionException - If there is a problem reading the useRawJNI parameter.