Package org.ptolemy.qss.util

Class ModelPolynomial

  • public final class ModelPolynomial
extends java.lang.Object
    Model of a variable that changes with time, using a polynomial.

    Represent a polynomial model:

    xModel{t} = c0 + c1*dt + c2*dt^2 + ...

    where

    • xModel{t}, model of some scalar variable x, as a function of time.
    • t, time of interest.
    • dt = t - tModel, time difference.
    • tModel, time of model formation.
    • c0, c1, c2, ..., model coefficients. The first coefficient is the value of x at tModel. The remaining coefficients are related to derivatives of x at tModel by ci = (1/i!)(d^i x/dt^i)(tModel). That is, they are the coefficients of the Taylor series expansion.
    • The notation g{y} means that g is a function of y.

    Need for a model time

    Each ModelPolynomial object needs to have an associated simulation time, in order to define the model. Add this simulation time by setting field this.tModel to the desired Time object. Failing to do so will cause a NullPointerException for most of the useful methods on this class.

    Alternative designs that would enforce this condition include:

    • Add a Time object to the constructor. This design was rejected because it implies that the model time is fixed, and should not be changed during the lifetime of the model.
    • Allocate a new Time object, with a default time, when constructing a ModelPoly object. This design was rejected because class Time is meant to be able to be swapped with other implementations, which may have different constructor needs.

    Purpose

    This class is meant to provide a lightweight capability for working with and exchanging models. The majority of data are kept public, in order to facilitate changing model coefficients without the overhead of accessor (setter, getter) calls.

    The design intention is that multiple objects in a system can share a single ModelPolynomial, in order to share a model of a common variable. In principle, at any given simulation time, only one of those objects should have "write access", and it alone should set the model parameters. The other objects in the system can use the model, but should refrain from changing it.

    Note that the ModelPolynomial object does nothing to enforce cooperation among readers and writers. It does, however, provide a simple counter for how many objects claim write access. This allows objects that intend to cooperate to double-check that they are doing so correctly.

    Since:
    Ptolemy II 11.0
    Version:
    $id$
    Author:
    David M. Lorenzetti. Contributor: Edward A. Lee
    Pt.AcceptedRating:
    red (reviewmoderator) // FIXME: Fill in.
    Pt.ProposedRating:
    red (dmlorenzetti)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      double[] coeffs
      Polynomial coefficients, in order: [c0, c1, c2, ...].
      Time tModel
      Simulation time at which model was formed, such that xModel{tModel} = c0.

    • Constructor Summary

      Constructors 
      Constructor Description
      ModelPolynomial​(int maxOrder)
      Construct a ModelPolynomial.

    • Field Detail

      • tModel

        public Time tModel
        Simulation time at which model was formed, such that xModel{tModel} = c0.

      • coeffs

        public final double[] coeffs
        Polynomial coefficients, in order: [c0, c1, c2, ...].

    • Constructor Detail

      • ModelPolynomial

        public ModelPolynomial​(int maxOrder)
        Construct a ModelPolynomial.
        Parameters:
        maxOrder - Maximum order of the polynomial (0=constant, 1=line, etc).

    • Method Detail

      • claimWriteAccess

        public final int claimWriteAccess()
        Claim write access.
        Returns:
        Count of all unique claims of write access (including caller).

      • evaluate

        public final double evaluate​(Time simTime)
        Evaluate the model at a simulation time.
        Parameters:
        simTime - Simulation time at which to evaluate the model.
        Returns:
        The model evaluated at a simulation time.

      • evaluate

        public final double evaluate​(double dt)
        Evaluate the model at a delta-time.
        Parameters:
        dt - Difference (simTime - tModel) at which to evaluate the model.
        Returns:
        The model evaluated at a delta-time.

      • evaluateDerivative

        public final double evaluateDerivative​(Time simTime)
        Evaluate d{model}/d{t} at a simulation time.
        Parameters:
        simTime - Simulation time at which to evaluate the derivative.
        Returns:
        The model derivative evaluated at a simulation time.

      • evaluateDerivative

        public final double evaluateDerivative​(double dt)
        Evaluate d{model}/d{t} at a delta-time.
        Parameters:
        dt - Difference (simTime - tModel) at which to evaluate the derivative.
        Returns:
        The model derivative evaluated at a delta-time.

      • evaluateDerivative2

        public final double evaluateDerivative2​(Time simTime)
        Evaluate d^2{model}/d{t}^2 at a simulation time.
        Parameters:
        simTime - Simulation time at which to evaluate the derivative.
        Returns:
        The model second derivative evaluated at a simulation time.

      • evaluateDerivative2

        public final double evaluateDerivative2​(double dt)
        Evaluate d^2{model}/d{t}^2 at a delta-time.
        Parameters:
        dt - Difference (simTime - tModel) at which to evaluate the derivative.
        Returns:
        The model second derivative evaluated at a delta-time.

      • getMaximumOrder

        public final int getMaximumOrder()
        Get the maximum order of the polynomial.
        Returns:
        The maximum order of the polynomial.

      • getWriterCount

        public final int getWriterCount()
        Find out how many objects claim write access.
        Returns:
        The number of objects that claim write access.

      • releaseWriteAccess

        public final int releaseWriteAccess()
        Release claim of write access.
        Returns:
        Count of all remaining claims of write access.

      • toString

        public final java.lang.String toString()
        Return a string representation of the model.
        Overrides:
        toString in class java.lang.Object
        Returns:
        The string representation of the model.