Package ptolemy.actor.lib.fmi

Class FMUQSS

  • All Implemented Interfaces:
    java.lang.Cloneable, DerivativeFunction, Actor, Advanceable, ContinuousStatefulComponent, ContinuousStepSizeController, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class FMUQSS
extends FMUImport
implements DerivativeFunction
    Invoke a Functional Mock-up Interface (FMI) 2.0 Model Exchange Functional Mock-up Unit (FMU) which will be integrated using QSS.

    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 for QSS integration, 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.

    This actor uses any QSS solver to integrate the FMUs for model exchange. A package of QSS solvers can be found in org.ptolemy.qss. This actor extends from FMUImport.java and should be used along with the QSSDirector.
    Since:
    Ptolemy II 11.0
    Version:
    $Id$
    Author:
    Thierry S. Nouidui, David M. Lorenzetti, Michael Wetter, Christopher Brooks.
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Red (cxh)

    • Field Detail

      • initFMUParameters

        public Parameter initFMUParameters
        If true, indicate the FMU to initialize parameters variables parameters. The default value is true.

      • eventDetection

        public Parameter eventDetection
        If true, indicate the FMU can do state/time/step event detection. The default value is true.

    • Method Detail

      • evaluateDerivatives

        public final int evaluateDerivatives​(Time time,
                                     double[] dtSample,
                                     double[] eventIndicatorVariableDerivatives,
                                     double[] eventIndicatorVariableDerivatives2,
                                     double[] eventIndicatorVariableDerivatives3,
                                     int order)
                              throws IllegalActionException
        Evaluate the derivative function for state event detection.
        Specified by:
        evaluateDerivatives in interface DerivativeFunction
        Parameters:
        time - The current simulation time.
        dtSample - The delta time used to approximate the first derivative.
        eventIndicatorVariableDerivatives - The (output) vector of time rates of change of the event indicators variables at time.
        eventIndicatorVariableDerivatives2 - The (output) vector of time rates of change of the event indicators variables.
        eventIndicatorVariableDerivatives3 - The (output) vector of time rates of change of the event indicators variables.
        order - The order.
        Returns:
        Success (0 for success, else user-defined error code).
        Throws:
        IllegalActionException - If an error occurred.

      • evaluateDerivatives

        public final int evaluateDerivatives​(Time time,
                                     double[] stateVariables,
                                     double[] inputVariables,
                                     double[] stateVariableDerivatives)
                              throws IllegalActionException
        Evaluate the derivative function.
        Specified by:
        evaluateDerivatives in interface DerivativeFunction
        Parameters:
        time - The current simulation time.
        stateVariables - The vector of state variables at time.
        inputVariables - The vector of input variables at time.
        stateVariableDerivatives - The (output) vector of time rates of change of the state variables at time.
        Returns:
        Success (0 for success, else user-defined error code).
        Throws:
        IllegalActionException - If using raw JNI throws it, if the time cannot be set, if the continuous states cannot be set or if the state count cannot be read.

      • evaluateDirectionalDerivatives

        public final double evaluateDirectionalDerivatives​(int stateDerivIndex,
                                                   double[] stateVariableDerivatives,
                                                   double[] inputVariableDerivatives)
                                            throws IllegalActionException
        Evaluate directional derivative and compute second derivative.
        Specified by:
        evaluateDirectionalDerivatives in interface DerivativeFunction
        Parameters:
        stateDerivIndex - The state derivative index.
        stateVariableDerivatives - The state derivatives.
        inputVariableDerivatives - The input derivatives.
        Returns:
        The directional derivative (see fmi2GetDirectionalDerivatives in FMI specification).
        Throws:
        IllegalActionException - If thrown while computing the directional derivative.

      • eventIndicatorDerivativeInputs

        public int eventIndicatorDerivativeInputs​(Time time,
                                          double[] stateVariables,
                                          double[] inputVariables,
                                          Time timeSample,
                                          double[] stateVariablesSample,
                                          double[] inputVariablesSample,
                                          double dtSample,
                                          Time timeSample2,
                                          double[] stateVariablesSample2,
                                          double[] inputVariablesSample2,
                                          double dtSample2,
                                          Time timeSample3,
                                          double[] stateVariablesSample3,
                                          double[] inputVariablesSample3,
                                          double dtSample3,
                                          Time timeSample4,
                                          double[] stateVariablesSample4,
                                          double[] inputVariablesSample4,
                                          double dtSample4,
                                          Time timeSample5,
                                          double[] stateVariablesSample5,
                                          double[] inputVariablesSample5,
                                          double dtSample5,
                                          int stateModelOrder)
                                   throws IllegalActionException
        Provide inputs to evaluate the derivative function for event indicators using finite difference methods.
        Specified by:
        eventIndicatorDerivativeInputs in interface DerivativeFunction
        Parameters:
        time - Simulation time.
        stateVariables - The vector of state variables at time.
        inputVariables - The vector of input variables at time.
        timeSample - Simulation time.
        stateVariablesSample - The vector of state variables at timeSample.
        inputVariablesSample - The vector of input variables at timeSample.
        dtSample - The delta between timeSample and time.
        timeSample2 - Simulation time.
        stateVariablesSample2 - The vector of state variables at timeSample2.
        inputVariablesSample2 - The vector of input variables at timeSample2.
        dtSample2 - The delta between timeSample2 and time.
        timeSample3 - Simulation time.
        stateVariablesSample3 - The vector of state variables at timeSample3.
        inputVariablesSample3 - The vector of input variables at timeSample3.
        dtSample3 - The delta between timeSample3 and time.
        timeSample4 - Simulation time.
        stateVariablesSample4 - The vector of state variables at timeSample4.
        inputVariablesSample4 - The vector of input variables at timeSample4.
        dtSample4 - The delta between timeSample4 and time.
        timeSample5 - Simulation time.
        stateVariablesSample5 - The vector of state variables at timeSample5.
        inputVariablesSample5 - The vector of input variables at timeSample5.
        dtSample5 - The delta between timeSample4 and time.
        stateModelOrder - The model order.
        Returns:
        Success (0 for success, else user-defined error code).
        Throws:
        IllegalActionException - If an error occurred.

      • fire

        public void fire()
          throws IllegalActionException
        Override the FMUImport base class to produce outputs.

        According to "System Design, Modeling, and Simulation Using Ptolemy II", version 1.02, section 12.3.1 "Execution Control": "The main computation of the actor is typically performed during the fire action, when it reads input data, performs computation, and produces output data."

        If it is time to produce a quantized output, produce it. 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 FMUImport
        Throws:
        IllegalActionException - If FMU indicates a failure.

      • getEventIndicatorCount

        public final int getEventIndicatorCount()
        Return the count of event indicator variables.
        Specified by:
        getEventIndicatorCount in interface DerivativeFunction
        Returns:
        The number of event indicator.

      • getInputVariableCount

        public final int getInputVariableCount()
        Return the count of input variables.
        Specified by:
        getInputVariableCount in interface DerivativeFunction
        Returns:
        The number of input variables.

      • getProvidesDirectionalDerivatives

        public final boolean getProvidesDirectionalDerivatives()
        Indicate existence of directional derivatives.
        Specified by:
        getProvidesDirectionalDerivatives in interface DerivativeFunction
        Returns:
        True if directional derivatives are provided.

      • getStateCount

        public final int getStateCount()
        Return the count of state variables.
        Specified by:
        getStateCount in interface DerivativeFunction
        Returns:
        The number of state variables.

      • importFMU

        public static void importFMU​(java.lang.Object originator,
                             FileParameter fmuFileParameter,
                             NamedObj context,
                             double x,
                             double y)
                      throws IllegalActionException,
                             java.io.IOException
        Override the importFMU in FMUImport base class.
        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.
        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.

        According to "System Design, Modeling, and Simulation Using Ptolemy II", version 1.02, section 12.3.1 "Execution Control": "The initialize action of the setup phase initializes parameters, resets local state, and sends out any initial messages."

        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class FMUImport
        Throws:
        IllegalActionException - If the slave FMU cannot be initialized.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Update the calculation of the next output time and request a refiring at that time.

        According to "System Design, Modeling, and Simulation Using Ptolemy II", version 1.02, section 12.3.1 "Execution Control": "An actor may have persistent state that evolves during execution; the postfire action updates that state in response to any inputs. The fact that the state of an actor is updated only in postfire is an important part of the actor abstract semantics..."

        If there is a new input, read it and update the slope.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class FMUImport
        Returns:
        True if the base class returns true.
        Throws:
        IllegalActionException - If reading inputs or parameters fails.

      • 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)
        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.
        Returns:
        FMU instance The index when fla is zero.

      • _acceptFMU

        protected static boolean _acceptFMU​(FMIModelDescription fmiModelDescription)
                             throws java.io.IOException
        Determine if the model description is acceptable. FMUQSS only works with FMI-2.0 (and later) model exchange fmus.
        Parameters:
        fmiModelDescription - The description of the model to be checked.
        Returns:
        true if the model description is acceptable.
        Throws:
        java.io.IOException - If the model description is not acceptable