Package com.irurueta.numerical.roots

Class ThirdDegreePolynomialRootsEstimator

java.lang.Object
com.irurueta.numerical.roots.RootEstimator
com.irurueta.numerical.roots.PolynomialRootsEstimator
com.irurueta.numerical.roots.ThirdDegreePolynomialRootsEstimator
public class ThirdDegreePolynomialRootsEstimator extends PolynomialRootsEstimator
Class to estimate the roots of a third degree polynomial along with other polynomial properties. A second degree polynomial is defined by its parameters as p(x) = a * x^3 + b * x^2 + c * x + d, hence the polynomial can be simply be defined by an array of length 4 [d, c, b, a] This class is based on: http://en.wikipedia.org/wiki/Cubic_function

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    EPS
    Constant defining machine precision.
    private double[]
    realPolyParams
    Array containing parameters of a second degree polynomial.
    static final double
    ROOT_THREE
    Constant defining the squared root of three.
    static final double
    THIRD
    Constant defining one third.
    static final int
    VALID_POLY_PARAMS_LENGTH
    Number of parameters valid for a third degree polynomial.

    Fields inherited from class com.irurueta.numerical.roots.PolynomialRootsEstimator

    polyParams, roots

    Fields inherited from class com.irurueta.numerical.roots.RootEstimator

    locked

  • Constructor Summary

    Constructors
    Constructor
    Description
    ThirdDegreePolynomialRootsEstimator()
    Empty constructor.
    ThirdDegreePolynomialRootsEstimator(double[] polyParams)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    arePolynomialParametersAvailable()
    Returns boolean indicating whether REAL polynomial parameters have been provided and is available for retrieval.
    private double
    cubeRoot(double x)
    Computes the cube root or x^(1/3) of provided value x
    void
    estimate()
    Estimates the roots of provided polynomial.
    private static double
    getDiscriminant(double[] polyParams)
    Internal method to compute the discriminant of a 3rd degree polynomial.
    com.irurueta.algebra.Complex[]
    getPolynomialParameters()
    This method will always raise a NotAvailableException because this class only supports REAL polynomial parameters.
    double[]
    getRealPolynomialParameters()
    Returns array of third degree polynomial parameters.
    boolean
    hasMultipleRealRoot()
    Returns boolean indicating whether the polynomial has two real and equal roots and a third different one (multiplicity 2), or all three roots are real and equal (multiplicity 3).
    static boolean
    hasMultipleRealRoot(double[] polyParams)
    Returns boolean indicating whether the polynomial has two real and equal roots and a third different one (multiplicity 2), or all three roots are real and equal (multiplicity 3).
    boolean
    hasOneRealRootAndTwoComplexConjugateRoots()
    Returns boolean indicating whether the polynomial has one real root and two complex conjugate roots.
    static boolean
    hasOneRealRootAndTwoComplexConjugateRoots(double[] polyParams)
    Returns boolean indicating whether the polynomial has one real root and two complex conjugate roots.
    boolean
    hasThreeDistinctRealRoots()
    Returns boolean indicating whether the roots of the polynomial are three distinct and real roots or not.
    static boolean
    hasThreeDistinctRealRoots(double[] polyParams)
    Returns boolean indicating whether the roots of the polynomial are three distinct and real roots or not.
    private void
    internalSetPolynomialParameters(double[] polyParams)
    Internal method to set array of third degree polynomial parameters.
    protected void
    internalSetPolynomialParameters(com.irurueta.algebra.Complex[] polyParams)
    This method will always raise an IllegalArgumentException because this class only supports REAL polynomial parameters.
    boolean
    isThirdDegree()
    Returns boolean indicating whether polynomial parameters provided to this instance correspond to a valid third degree polynomial.
    static boolean
    isThirdDegree(double[] polyParams)
    Returns boolean indicating whether provided array of polynomial parameters correspond to a valid third degree polynomial.
    void
    setPolynomialParameters(double[] polyParams)
    Set array of third degree polynomial parameters.
    private void
    solveCubic(double a, double b, double c, double d, com.irurueta.algebra.Complex x1, com.irurueta.algebra.Complex x2, com.irurueta.algebra.Complex x3)
    Finds 3rd degree polynomial roots

    Methods inherited from class com.irurueta.numerical.roots.PolynomialRootsEstimator

    areRootsAvailable, getRoots, isReady, setPolynomialParameters

    Methods inherited from class com.irurueta.numerical.roots.RootEstimator

    isLocked

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • EPS

      public static final double EPS
      Constant defining machine precision.
      See Also:

    • THIRD

      public static final double THIRD
      Constant defining one third.
      See Also:

    • ROOT_THREE

      public static final double ROOT_THREE
      Constant defining the squared root of three.

    • VALID_POLY_PARAMS_LENGTH

      public static final int VALID_POLY_PARAMS_LENGTH
      Number of parameters valid for a third degree polynomial.
      See Also:

    • realPolyParams

      private double[] realPolyParams
      Array containing parameters of a second degree polynomial.

  • Constructor Details

    • ThirdDegreePolynomialRootsEstimator

      public ThirdDegreePolynomialRootsEstimator()
      Empty constructor.

    • ThirdDegreePolynomialRootsEstimator

      public ThirdDegreePolynomialRootsEstimator(double[] polyParams)
      Constructor.
      Parameters:
      polyParams - Array containing polynomial parameters.
      Throws:
      IllegalArgumentException - Raised if the length of the provided array is not valid.

  • Method Details

    • setPolynomialParameters

      public void setPolynomialParameters(double[] polyParams) throws LockedException
      Set array of third degree polynomial parameters. A third degree polynomial is defined by p(x) = a * x^3 + b * x^2 + c * x + d, and the array must be provided as [d, c, b, a]. Note: This class only supports real polynomial parameters
      Parameters:
      polyParams - Array containing polynomial parameters
      Throws:
      LockedException - Raised if this instance is locked
      IllegalArgumentException - Raised if the length of the provided array is not valid.

    • internalSetPolynomialParameters

      private void internalSetPolynomialParameters(double[] polyParams)
      Internal method to set array of third degree polynomial parameters. A third degree polynomial is defined by p(x) = a * x^3 + b * x^2 + c * d + d, and the array must be provided as [d, c, b, a]. Note: This class only supports real polynomial parameters This method does not check if this instance is locked.
      Parameters:
      polyParams - Array containing polynomial parameters
      Throws:
      IllegalArgumentException - Raised if the length of the provided array is not valid.

    • getRealPolynomialParameters

      public double[] getRealPolynomialParameters() throws NotAvailableException
      Returns array of third degree polynomial parameters. A third degree polynomial is defined by p(x) = a * x^3 + b * x^2 + c * x + d, and the array is returned as [d, c, b, a]. Note: This class only supports real polynomial parameters.
      Returns:
      Array of first degree polynomial parameters.
      Throws:
      NotAvailableException - Raised if polynomial parameter have not yet been provided.

    • arePolynomialParametersAvailable

      public boolean arePolynomialParametersAvailable()
      Returns boolean indicating whether REAL polynomial parameters have been provided and is available for retrieval. Note: This class only supports real polynomial parameters.
      Overrides:
      arePolynomialParametersAvailable in class PolynomialRootsEstimator
      Returns:
      True if available, false otherwise.

    • getPolynomialParameters

      public com.irurueta.algebra.Complex[] getPolynomialParameters() throws NotAvailableException
      This method will always raise a NotAvailableException because this class only supports REAL polynomial parameters.
      Overrides:
      getPolynomialParameters in class PolynomialRootsEstimator
      Returns:
      this method always throws an exception.
      Throws:
      NotAvailableException - always thrown

    • estimate

      public void estimate() throws LockedException, NotReadyException, RootEstimationException
      Estimates the roots of provided polynomial.
      Overrides:
      estimate in class RootEstimator
      Throws:
      LockedException - Raised if this instance is locked estimating roots.
      NotReadyException - Raised if this instance is not ready because polynomial parameters have not been provided.
      RootEstimationException - Raised if roots cannot be estimated for some reason.

    • isThirdDegree

      public static boolean isThirdDegree(double[] polyParams)
      Returns boolean indicating whether provided array of polynomial parameters correspond to a valid third degree polynomial. A third degree polynomial is defined by p(x) = a * x^3 + b * x^2 + c *x + d, and the array is returned as [d, c, b, a]. Note: This class only supports real polynomial parameters
      Parameters:
      polyParams - Array containing polynomial parameters
      Returns:
      True if is a third degree polynomial, false otherwise

    • isThirdDegree

      public boolean isThirdDegree() throws NotReadyException
      Returns boolean indicating whether polynomial parameters provided to this instance correspond to a valid third degree polynomial. A third degree polynomial is defined by p(x) = a * x^3 + b * x^2 + c * x + d, and the array is returned as [d, c, b, a]. Note: This class only supports real polynomial parameters
      Returns:
      True if is a second degree polynomial, false otherwise
      Throws:
      NotReadyException - Raised if this instance is not ready because an array of polynomial parameters has not yet been provided.

    • hasThreeDistinctRealRoots

      public static boolean hasThreeDistinctRealRoots(double[] polyParams)
      Returns boolean indicating whether the roots of the polynomial are three distinct and real roots or not. Because this class only supports polynomials with real parameters, we know that for third degree polynomials that have three distinct roots, they must be either real or one real and 2 complex conjugate.
      Parameters:
      polyParams - Array containing polynomial parameters
      Returns:
      True if roots are distinct and real, false otherwise

    • hasThreeDistinctRealRoots

      public boolean hasThreeDistinctRealRoots() throws NotReadyException
      Returns boolean indicating whether the roots of the polynomial are three distinct and real roots or not. Because this class only supports polynomials with real parameters, we know that for third degree polynomials that have three distinct roots, they must be either real or one real and 2 complex conjugate.
      Returns:
      True if roots are distinct and real, false otherwise
      Throws:
      NotReadyException - Raised if polynomial parameters haven't yet been provided

    • hasMultipleRealRoot

      public static boolean hasMultipleRealRoot(double[] polyParams)
      Returns boolean indicating whether the polynomial has two real and equal roots and a third different one (multiplicity 2), or all three roots are real and equal (multiplicity 3).
      Parameters:
      polyParams - Array containing polynomial parameters
      Returns:
      True if there are roots with multiplicity greater than one, false otherwise

    • hasMultipleRealRoot

      public boolean hasMultipleRealRoot() throws NotReadyException
      Returns boolean indicating whether the polynomial has two real and equal roots and a third different one (multiplicity 2), or all three roots are real and equal (multiplicity 3).
      Returns:
      True if there are roots with multiplicity greater than one, false otherwise
      Throws:
      NotReadyException - Raised if polynomial parameters haven't yet been provided

    • hasOneRealRootAndTwoComplexConjugateRoots

      public static boolean hasOneRealRootAndTwoComplexConjugateRoots(double[] polyParams)
      Returns boolean indicating whether the polynomial has one real root and two complex conjugate roots.
      Parameters:
      polyParams - Array containing polynomial parameters
      Returns:
      True if polynomial has 1 real root and 2 complex conjugate roots, false otherwise

    • hasOneRealRootAndTwoComplexConjugateRoots

      public boolean hasOneRealRootAndTwoComplexConjugateRoots() throws NotReadyException
      Returns boolean indicating whether the polynomial has one real root and two complex conjugate roots.
      Returns:
      True if polynomial has 1 real root and 2 complex conjugate roots, false otherwise
      Throws:
      NotReadyException - Raised if polynomial parameters haven't yet been provided

    • internalSetPolynomialParameters

      protected void internalSetPolynomialParameters(com.irurueta.algebra.Complex[] polyParams)
      This method will always raise an IllegalArgumentException because this class only supports REAL polynomial parameters.
      Specified by:
      internalSetPolynomialParameters in class PolynomialRootsEstimator
      Parameters:
      polyParams - Polynomial parameters.
      Throws:
      IllegalArgumentException - always thrown.

    • getDiscriminant

      private static double getDiscriminant(double[] polyParams)
      Internal method to compute the discriminant of a 3rd degree polynomial. Discriminants are helpful to determine properties of a 3rd degree polynomial
      Parameters:
      polyParams - Array containing polynomial parameters
      Returns:
      Value of discriminant

    • cubeRoot

      private double cubeRoot(double x)
      Computes the cube root or x^(1/3) of provided value x
      Parameters:
      x - Provided value
      Returns:
      Cube root

    • solveCubic

      private void solveCubic(double a, double b, double c, double d, com.irurueta.algebra.Complex x1, com.irurueta.algebra.Complex x2, com.irurueta.algebra.Complex x3)
      Finds 3rd degree polynomial roots
      Parameters:
      a - 1st parameter
      b - 2nd parameter
      c - 3rd parameter
      d - 4th parameter
      x1 - 1st root (output parameter)
      x2 - 2nd root (output parameter)
      x3 - 3rd root (output parameter)