org.apache.commons.math3.analysis.polynomials

## Class PolynomialFunction

- java.lang.Object
- - org.apache.commons.math3.analysis.polynomials.PolynomialFunction

- All Implemented Interfaces:
    Serializable, DifferentiableUnivariateFunction, UnivariateDifferentiableFunction, UnivariateFunction

      public class PolynomialFunction
      extends Object
      implements UnivariateDifferentiableFunction, DifferentiableUnivariateFunction, Serializable

  Immutable representation of a real polynomial function with real coefficients.

  Horner's Method is used to evaluate the function.

  Version:
    $Id: PolynomialFunction.java 1383441 2012-09-11 14:56:39Z luc $
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `PolynomialFunction.Parametric` Dedicated parametric polynomial class.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private double[]` | `coefficients` The coefficients of the polynomial, ordered by degree -- i.e., coefficients[0] is the constant term and coefficients[n] is the coefficient of x^n where n is the degree of the polynomial.
    `private static long` | `serialVersionUID` Serialization identifier

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PolynomialFunction(double[] c)` Construct a polynomial with the given coefficients.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `PolynomialFunction` | `add(PolynomialFunction p)` Add a polynomial to the instance.
    `int` | `degree()` Returns the degree of the polynomial.
    `UnivariateFunction` | `derivative()` Returns the derivative as a `UnivariateFunction`.
    `protected static double[]` | `differentiate(double[] coefficients)` Returns the coefficients of the derivative of the polynomial with the given coefficients.
    `boolean` | `equals(Object obj)`
    `protected static double` | `evaluate(double[] coefficients, double argument)` Uses Horner's Method to evaluate the polynomial with the given coefficients at the argument.
    `double[]` | `getCoefficients()` Returns a copy of the coefficients array.
    `int` | `hashCode()`
    `PolynomialFunction` | `multiply(PolynomialFunction p)` Multiply the instance by a polynomial.
    `PolynomialFunction` | `negate()` Negate the instance.
    `PolynomialFunction` | `polynomialDerivative()` Returns the derivative as a `PolynomialFunction`.
    `PolynomialFunction` | `subtract(PolynomialFunction p)` Subtract a polynomial from the instance.
    `String` | `toString()` Returns a string representation of the polynomial.
    `private static String` | `toString(double coeff)` Creates a string representing a coefficient, removing ".0" endings.
    `DerivativeStructure` | `value(DerivativeStructure t)` Simple mathematical function.
    `double` | `value(double x)` Compute the value of the function for the given argument.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### serialVersionUID

          private static final long serialVersionUID

      Serialization identifier
      See Also:
        Constant Field Values

    - #### coefficients

          private final double[] coefficients

      The coefficients of the polynomial, ordered by degree -- i.e., coefficients[0] is the constant term and coefficients[n] is the coefficient of x^n where n is the degree of the polynomial.

  - ### Constructor Detail

    - #### PolynomialFunction

          public PolynomialFunction(double[] c)
                             throws NullArgumentException,
                                    NoDataException

      Construct a polynomial with the given coefficients. The first element of the coefficients array is the constant term. Higher degree coefficients follow in sequence. The degree of the resulting polynomial is the index of the last non-null element of the array, or 0 if all elements are null.

      The constructor makes a copy of the input array and assigns the copy to the coefficients property.

      Parameters:
        `c` - Polynomial coefficients.
      Throws:
        `NullArgumentException` - if `c` is `null`.
        `NoDataException` - if `c` is empty.

  - ### Method Detail

    - #### value

          public double value(double x)

      Compute the value of the function for the given argument.

      The value returned is
      `coefficients[n] * x^n + ... + coefficients[1] * x + coefficients[0]`

      Specified by:
        `value` in interface `UnivariateFunction`
      Parameters:
        `x` - Argument for which the function value should be computed.
      Returns:
        the value of the polynomial at the given point.
      See Also:
        `UnivariateFunction.value(double)`

    - #### degree

          public int degree()

      Returns the degree of the polynomial.
      Returns:
        the degree of the polynomial.

    - #### getCoefficients

          public double[] getCoefficients()

      Returns a copy of the coefficients array.

      Changes made to the returned copy will not affect the coefficients of the polynomial.

      Returns:
        a fresh copy of the coefficients array.

    - #### evaluate

          protected static double evaluate(double[] coefficients,
                        double argument)
                                    throws NullArgumentException,
                                           NoDataException

      Uses Horner's Method to evaluate the polynomial with the given coefficients at the argument.
      Parameters:
        `coefficients` - Coefficients of the polynomial to evaluate.
        `argument` - Input value.
      Returns:
        the value of the polynomial.
      Throws:
        `NoDataException` - if `coefficients` is empty.
        `NullArgumentException` - if `coefficients` is `null`.

    - #### value

          public DerivativeStructure value(DerivativeStructure t)
                                    throws NullArgumentException,
                                           NoDataException

      Simple mathematical function.

      `UnivariateDifferentiableFunction` classes compute both the value and the first derivative of the function.

      Specified by:
        `value` in interface `UnivariateDifferentiableFunction`
      Parameters:
        `t` - function input value
      Returns:
        function result
      Throws:
        `NoDataException` - if `coefficients` is empty.
        `NullArgumentException` - if `coefficients` is `null`.
      Since:
        3.1

    - #### add

          public PolynomialFunction add(PolynomialFunction p)

      Add a polynomial to the instance.
      Parameters:
        `p` - Polynomial to add.
      Returns:
        a new polynomial which is the sum of the instance and `p`.

    - #### subtract

          public PolynomialFunction subtract(PolynomialFunction p)

      Subtract a polynomial from the instance.
      Parameters:
        `p` - Polynomial to subtract.
      Returns:
        a new polynomial which is the difference the instance minus `p`.

    - #### negate

          public PolynomialFunction negate()

      Negate the instance.
      Returns:
        a new polynomial.

    - #### multiply

          public PolynomialFunction multiply(PolynomialFunction p)

      Multiply the instance by a polynomial.
      Parameters:
        `p` - Polynomial to multiply by.
      Returns:
        a new polynomial.

    - #### differentiate

          protected static double[] differentiate(double[] coefficients)
                                           throws NullArgumentException,
                                                  NoDataException

      Returns the coefficients of the derivative of the polynomial with the given coefficients.
      Parameters:
        `coefficients` - Coefficients of the polynomial to differentiate.
      Returns:
        the coefficients of the derivative or `null` if coefficients has length 1.
      Throws:
        `NoDataException` - if `coefficients` is empty.
        `NullArgumentException` - if `coefficients` is `null`.

    - #### polynomialDerivative

          public PolynomialFunction polynomialDerivative()

      Returns the derivative as a `PolynomialFunction`.
      Returns:
        the derivative polynomial.

    - #### derivative

          public UnivariateFunction derivative()

      Returns the derivative as a `UnivariateFunction`.
      Specified by:
        `derivative` in interface `DifferentiableUnivariateFunction`
      Returns:
        the derivative function.

    - #### toString

          public String toString()

      Returns a string representation of the polynomial.

      The representation is user oriented. Terms are displayed lowest degrees first. The multiplications signs, coefficients equals to one and null terms are not displayed (except if the polynomial is 0, in which case the 0 constant term is displayed). Addition of terms with negative coefficients are replaced by subtraction of terms with positive coefficients except for the first displayed term (i.e. we display `-3` for a constant negative polynomial, but `1 - 3 x + x^2` if the negative coefficient is not the first one displayed).

      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of the polynomial.

    - #### toString

          private static String toString(double coeff)

      Creates a string representing a coefficient, removing ".0" endings.
      Parameters:
        `coeff` - Coefficient.
      Returns:
        a string representation of `coeff`.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

Copyright (c) 2003-2013 Apache Software Foundation