org.apache.commons.math.analysis.polynomials

## Class PolynomialFunctionLagrangeForm

- java.lang.Object
- - org.apache.commons.math.analysis.polynomials.PolynomialFunctionLagrangeForm

- All Implemented Interfaces:
    UnivariateRealFunction

      public class PolynomialFunctionLagrangeForm
      extends Object
      implements UnivariateRealFunction

  Implements the representation of a real polynomial function in Lagrange Form. For reference, see Introduction to Numerical Analysis, ISBN 038795452X, chapter 2.

  The approximated function should be smooth enough for Lagrange polynomial to work well. Otherwise, consider using splines instead.

  Since:
    1.2
  Version:
    $Revision: 1073498 $ $Date: 2011-02-22 21:57:26 +0100 (mar. 22 févr. 2011) $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private double[]` | `coefficients` The coefficients of the polynomial, ordered by degree -- i.e.
    `private boolean` | `coefficientsComputed` Whether the polynomial coefficients are available.
    `private double[]` | `x` Interpolating points (abscissas).
    `private double[]` | `y` Function values at interpolating points.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PolynomialFunctionLagrangeForm(double[] x, double[] y)` Construct a Lagrange polynomial with the given abscissas and function values.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `computeCoefficients()` Calculate the coefficients of Lagrange polynomial from the interpolation data.
    `int` | `degree()` Returns the degree of the polynomial.
    `static double` | `evaluate(double[] x, double[] y, double z)` Evaluate the Lagrange polynomial using Neville's Algorithm.
    `double[]` | `getCoefficients()` Returns a copy of the coefficients array.
    `double[]` | `getInterpolatingPoints()` Returns a copy of the interpolating points array.
    `double[]` | `getInterpolatingValues()` Returns a copy of the interpolating values array.
    `double` | `value(double z)` Compute the value for the function.
    `static void` | `verifyInterpolationArray(double[] x, double[] y)` Verifies that the interpolation arrays are valid.

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

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

- - ### Field Detail

    - #### coefficients

          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.

    - #### x

          private final double[] x

      Interpolating points (abscissas).

    - #### y

          private final double[] y

      Function values at interpolating points.

    - #### coefficientsComputed

          private boolean coefficientsComputed

      Whether the polynomial coefficients are available.

  - ### Constructor Detail

    - #### PolynomialFunctionLagrangeForm

          public PolynomialFunctionLagrangeForm(double[] x,
                                        double[] y)
                                         throws IllegalArgumentException

      Construct a Lagrange polynomial with the given abscissas and function values. The order of interpolating points are not important.

      The constructor makes copy of the input arrays and assigns them.

      Parameters:
        `x` - interpolating points
        `y` - function values at interpolating points
      Throws:
        `IllegalArgumentException` - if input arrays are not valid

  - ### Method Detail

    - #### value

          public double value(double z)
                       throws FunctionEvaluationException

      Compute the value for the function.
      Specified by:
        `value` in interface `UnivariateRealFunction`
      Parameters:
        `z` - the point for which the function value should be computed
      Returns:
        the value
      Throws:
        `FunctionEvaluationException` - if the function evaluation fails

    - #### degree

          public int degree()

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

    - #### getInterpolatingPoints

          public double[] getInterpolatingPoints()

      Returns a copy of the interpolating points array.

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

      Returns:
        a fresh copy of the interpolating points array

    - #### getInterpolatingValues

          public double[] getInterpolatingValues()

      Returns a copy of the interpolating values array.

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

      Returns:
        a fresh copy of the interpolating values array

    - #### getCoefficients

          public double[] getCoefficients()

      Returns a copy of the coefficients array.

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

      Note that coefficients computation can be ill-conditioned. Use with caution and only when it is necessary.

      Returns:
        a fresh copy of the coefficients array

    - #### evaluate

          public static double evaluate(double[] x,
                        double[] y,
                        double z)
                                 throws DuplicateSampleAbscissaException,
                                        IllegalArgumentException

      Evaluate the Lagrange polynomial using Neville's Algorithm. It takes O(N^2) time.

      This function is made public static so that users can call it directly without instantiating PolynomialFunctionLagrangeForm object.

      Parameters:
        `x` - the interpolating points array
        `y` - the interpolating values array
        `z` - the point at which the function value is to be computed
      Returns:
        the function value
      Throws:
        `DuplicateSampleAbscissaException` - if the sample has duplicate abscissas
        `IllegalArgumentException` - if inputs are not valid

    - #### computeCoefficients

          protected void computeCoefficients()
                                      throws ArithmeticException

      Calculate the coefficients of Lagrange polynomial from the interpolation data. It takes O(N^2) time.

      Note this computation can be ill-conditioned. Use with caution and only when it is necessary.

      Throws:
        `ArithmeticException` - if any abscissas coincide

    - #### verifyInterpolationArray

          public static void verifyInterpolationArray(double[] x,
                                      double[] y)
                                               throws IllegalArgumentException

      Verifies that the interpolation arrays are valid.

      The arrays features checked by this method are that both arrays have the same length and this length is at least 2.

      The interpolating points must be distinct. However it is not verified here, it is checked in evaluate() and computeCoefficients().

      Parameters:
        `x` - the interpolating points array
        `y` - the interpolating values array
      Throws:
        `IllegalArgumentException` - if not valid
      See Also:
        `evaluate(double[], double[], double)`, `computeCoefficients()`

Copyright (c) 2003-2013 Apache Software Foundation