org.ptolemy.qss.util

Interface DerivativeFunction

All Known Implementing Classes:

FMUQSS, QSSIntegrator

public interface DerivativeFunction

Provide an interface for representing derivative functions.

The interface encapsulates the derivatives of one or more state variables, x, as:

xdot = f{t, x, u}

where

• t, simulation time.
• x, vector of state variables, x{t}.
• u, vector of input variables, u{t}.
• xdot, vector of time rates of change of the state variables. That is, xdot = dx/dt.
• f, vector-valued derivative function.
• The notation g{y} means that g is a function of y.

Expected implementation conventions

An implementing class should enforce:

• The count of state variables Nx > 0.
• The count of input variables Nu >= 0.

Since:

Ptolemy II 11.0

Version:

$id$

Author:

David M. Lorenzetti, Contributor: Thierry S. Nouidui

Pt.AcceptedRating:

red (reviewmoderator) // FIXME: Fill in.

Pt.ProposedRating:

red (dmlorenzetti)

Method Summary

Modifier and Type	Method and Description
int	evaluateDerivatives(Time time, double[] xx, double[] uu, double[] xdot) Evaluate the derivative function.
int	evaluateDerivatives(Time time, double[] dtSample, double[] xdot, double[] xdotSample, double[] xdotSample2, int stOrd) Evaluate the derivative function for event indicator.
double	evaluateDirectionalDerivatives(int idx, double[] xx_dot, double[] uu_dot) Evaluate directional derivative function.
int	eventIndicatorDerivativeInputs(Time time, double[] xx, double[] uu, Time timeSample, double[] xxSample, double[] uuSample, double dtSample, Time timeSample2, double[] xxSample2, double[] uuSample2, double dtSample2, Time timeSample3, double[] xxSample3, double[] uuSample3, double dtSample3, Time timeSample4, double[] xxSample4, double[] uuSample4, double dtSample4, Time timeSample5, double[] xxSample5, double[] uuSample5, double dtSample5, int stateModelOrder) Provide inputs to evaluate the derivative function using finite difference methods.
int	getEventIndicatorCount() Return the number of event indicators.
int	getInputVariableCount() Return the count of input variables.
boolean	getProvidesDirectionalDerivatives() Indicate existence of directional derivatives.
int	getStateCount() Return the count of state variables.

Method Detail

evaluateDerivatives

int evaluateDerivatives(Time time,
                        double[] dtSample,
                        double[] xdot,
                        double[] xdotSample,
                        double[] xdotSample2,
                        int stOrd)
                 throws IllegalActionException

Evaluate the derivative function for event indicator. An implementation of this function is expected to fill in the xdot and xdotSample array with derivatives values.

Parameters:

time - The time.

dtSample - The delta time used to approximate first derivative.

xdot - The vector of time rates of change of the state variables at time.

xdotSample - The vector of time rates of change of the state variables at a sample time.

xdotSample2 - The vector of time rates of change of the state variables at a sample time.

stOrd - The state model order.

Returns:

Success (0 for success, else user-defined error code).

Throws:

IllegalActionException - If derivatives cannot be evaluated.

evaluateDerivatives

int evaluateDerivatives(Time time,
                        double[] xx,
                        double[] uu,
                        double[] xdot)
                 throws IllegalActionException

Evaluate the derivative function. An implementation of this function is expected to fill in the xdot array with values calculated using the time, xx, and uu input arrays. A caller of this function is expected to provide an xdot array whose length exactly equals that of the xx input array. The length of the uu array should equal the value returned by getInputVariableCount(), and the length of the xx and xdot arrays should equal the value returned by getStateCount().

Expected implementation conventions:

• The state variable vector has at least one element.
• The method does not change any entry in uu.
• If the derivative function does not take any input variables, then uu == null.

Parameters:

time - Simulation time.

xx - The vector of state variables at time.

uu - The vector of input variables at time.

xdot - The 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 derivatives cannot be evaluated.

evaluateDirectionalDerivatives

double evaluateDirectionalDerivatives(int idx,
                                      double[] xx_dot,
                                      double[] uu_dot)
                               throws IllegalActionException

Evaluate directional derivative function. An implementation of this function is expected to return the directional derivative of a state derivative with index idx calculated using the xx_dot, and uu_dot input arrays. A caller of this function is expected to provide an xx_dot array, and an uu_dot array. The length of the uu_dot array should equal the value returned by getInputVariableCount(), and the length of the xx_dot arrays should equal the value returned by getStateCount().

Parameters:

idx - The state derivative index.

xx_dot - The vector of state derivatives.

uu_dot - The vector of input derivatives.

Returns:

The directional derivative (see fmi2GetDirectionalDerivatives in FMI specification).

Throws:

IllegalActionException - If directional derivatives cannot be evaluated.

eventIndicatorDerivativeInputs

int eventIndicatorDerivativeInputs(Time time,
                                   double[] xx,
                                   double[] uu,
                                   Time timeSample,
                                   double[] xxSample,
                                   double[] uuSample,
                                   double dtSample,
                                   Time timeSample2,
                                   double[] xxSample2,
                                   double[] uuSample2,
                                   double dtSample2,
                                   Time timeSample3,
                                   double[] xxSample3,
                                   double[] uuSample3,
                                   double dtSample3,
                                   Time timeSample4,
                                   double[] xxSample4,
                                   double[] uuSample4,
                                   double dtSample4,
                                   Time timeSample5,
                                   double[] xxSample5,
                                   double[] uuSample5,
                                   double dtSample5,
                                   int stateModelOrder)
                            throws IllegalActionException

Provide inputs to evaluate the derivative function using finite difference methods. An implementation of this function is expected to use the input parameters time, xx, uu input, timeSample, xxSample, and uuSample arrays to compute the derivatives for event indicators.

Parameters:

time - Simulation time.

xx - The vector of state variables at time.

uu - The vector of input variables at time.

timeSample - Simulation time.

xxSample - The vector of state variables at timeSample.

uuSample - The vector of input variables at timeSample.

dtSample - The delta between timeSample and time.

timeSample2 - Simulation time.

xxSample2 - The vector of state variables at timeSample2.

uuSample2 - The vector of input variables at timeSample2.

dtSample2 - The delta between timeSample2 and time.

timeSample3 - Simulation time.

xxSample3 - The vector of state variables at timeSample3.

uuSample3 - The vector of input variables at timeSample3.

dtSample3 - The delta between timeSample3 and time.

timeSample4 - Simulation time.

xxSample4 - The vector of state variables at timeSample4.

uuSample4 - The vector of input variables at timeSample4.

dtSample4 - The delta between timeSample4 and time. variables at time.

timeSample5 - Simulation time.

xxSample5 - The vector of state variables at timeSample5.

uuSample5 - The vector of input variables at timeSample5.

dtSample5 - The delta between timeSample5 and time. variables at time.

stateModelOrder - The order of the model.

Returns:

Success (0 for success, else user-defined error code).

Throws:

IllegalActionException - If derivatives cannot be evaluated.

getEventIndicatorCount

int getEventIndicatorCount()

Return the number of event indicators.

Returns:

Count of event indicators.

getInputVariableCount

int getInputVariableCount()

Return the count of input variables.

Expect 0 ≤ this.getInputVarCt().

Returns:

Count of input variables.

getProvidesDirectionalDerivatives

boolean getProvidesDirectionalDerivatives()

Indicate existence of directional derivatives.

Prescribed by interface DerivativeFcn.

Returns:

True if directional derivatives are provided.

getStateCount

int getStateCount()

Return the count of state variables.

Expect 0 < this.getStateCt().

Returns:

Count of state variables.