/*

  * Licensed to the Apache Software Foundation (ASF) under one or more

  * contributor license agreements.  See the NOTICE file distributed with

  * this work for additional information regarding copyright ownership.

  * The ASF licenses this file to You under the Apache License, Version 2.0

  * (the "License"); you may not use this file except in compliance with

  * the License.  You may obtain a copy of the License at

  *

  *      http://www.apache.org/licenses/LICENSE-2.0

  *

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package org.apache.commons.nabla.differences;

 import java.io.Serializable;

 import org.apache.commons.nabla.core.UnivariateDifferentiator;

 /** This class represents a differentiation scheme based on finite differences.

  * <p>The differences are based on regularly distributed points around the

  * central test point according to a given h step.

  * For example a four points scheme would use a linear combination of points

  * <code>f(x-2h)</code>, <code>f(x-h)</code>, <code>f(x+h)</code> and

  * <code>f(x+2h)</code> to compute the first derivative <code>f'(x)</code>

  * (note that <code>f(x)</code> by itself is not used for the evaluation of

  * <code>f'(x)</code>, but is used to compute the value of the function

  * <code>f(x)</code).</p>

  * <p>The computed differential is only an approximation. The error depends on

  * the value of the high order derivatives of the function which were not

  * canceled by the linear combination, the number of points and the step size.

  * For example the four points scheme cancels the

  * <code>f<sup>(2)</sup></code>, <code>f<sup>(3)</sup></code> and

  * <code>f<sup>(4)</sup></code> high order derivatives but not the

  * <code>f<sup>(5)</sup></code> and higher order terms. The theoretical error

  * model for this scheme is <code>-2h<sup>4</sup>/5 f<sup>(5)</sup>(x) +

  * O(h<sup>6</sup>)</code>. This model doesn't take into account numerical

  * cancellation which occur when the steps are too small.</p>

  * <p>The general expression of the theoretical error model is

  * <code>A f<sup>(k)</sup> + O(h<sup>k+1</sup>)</code> where <code>A</code>

  * is the value returned by {@link #getSignedErrorScaleFactor()} and

  * <code>k</code> is the value returned by {@link #getOrderFirstNonCanceled()}.</p>

  */

 public abstract class FiniteDifferencesDifferentiator

     implements UnivariateDifferentiator, Serializable {

     /** Step size. */

     private final double stepSize;

     /** Error scale factor. */

     private final double factor;

     /** Order of the first non-canceled derivative. */

     private final int order;

     /** Simple constructor.

      * @param stepSize step stepSize

      * @param factor error scale factor

      * @param order order of the first non-canceled derivative

      */

     protected FiniteDifferencesDifferentiator(final double stepSize,

                                               final double factor,

                                               final int order) {

         this.stepSize = stepSize;

         this.factor   = factor;

         this.order    = order;

     }

     /** Get the signed error scale factor for the finite differences scheme.

      * <p>The error scale factor is the value of the h-dependent

      * factor of the first non-canceled high order differential of the function.

      * For example since the error model for the four points scheme is

      * <code>-2h<sup>4</sup>/5 f<sup>(5)</sup>(x) + O(h<sup>6</sup>)</code>,

      * the signed error scale factor is <code>-2h<sup>4</sup>/5</code>.</p>

      * @return error signed scale factor

      * @see #getOrderFirstNonCanceled()

      */

     public double getSignedErrorScaleFactor() {

         return factor;

     }

     /** Get the order of the first non-canceled derivative.

      * <p>The error model of the scheme depends on the first non-canceled

      * high order differential of the function. For example since the error

      * model for the four points scheme is <code>-2h<sup>4</sup>/5

      * f<sup>(5)</sup>(x) + O(h<sup>6</sup>)</code>, the order of the first

      * non-canceled derivative is 5.

      * @return order of the first non-canceled derivative

      * @see #getSignedErrorScaleFactor()

      */

     public int getOrderFirstNonCanceled() {

         return order;

     }

     /** Get the step size.

      * @return step size

      */

     protected double getStepSize() {

         return stepSize;

     }

 }