commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject svn commit: r476930 [5/22] - in /jakarta/commons/proper/math/trunk/src/mantissa: ./ src/ src/org/ src/org/spaceroots/ src/org/spaceroots/mantissa/ src/org/spaceroots/mantissa/algebra/ src/org/spaceroots/mantissa/estimation/ src/org/spaceroots/mantissa/...
Date Sun, 19 Nov 2006 21:36:23 GMT
Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/AbstractCurveFitter.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/AbstractCurveFitter.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/AbstractCurveFitter.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/AbstractCurveFitter.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,286 @@
+// 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.spaceroots.mantissa.fitting;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Iterator;
+
+import org.spaceroots.mantissa.estimation.*;
+
+/** This class is the base class for all curve fitting classes in the package.
+
+ * <p>This class handles all common features of curve fitting like the
+ * sample points handling. It declares two methods ({@link
+ * #valueAt} and {@link #partial}) which should be implemented by
+ * sub-classes to define the precise shape of the curve they
+ * represent.</p>
+
+ * @version $Id: AbstractCurveFitter.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+
+public abstract class AbstractCurveFitter
+  implements EstimationProblem, Serializable {
+
+  /**
+   * Simple constructor.
+   * @param n number of coefficients in the underlying function
+   * @param maxIterations maximum number of iterations allowed
+   * @param convergence criterion threshold below which we do not need
+   * to improve the criterion anymore
+   * @param steadyStateThreshold steady state detection threshold, the
+   * problem has reached a steady state (read converged) if
+   * <code>Math.abs (Jn - Jn-1) < Jn * convergence</code>, where
+   * <code>Jn</code> and <code>Jn-1</code> are the current and
+   * preceding criterion value (square sum of the weighted residuals
+   * of considered measurements).
+   * @param epsilon threshold under which the matrix of the linearized
+   * problem is considered singular (see {@link
+   * org.spaceroots.mantissa.linalg.SquareMatrix#solve(
+   * org.spaceroots.mantissa.linalg.Matrix,double) SquareMatrix.solve}).
+   */
+  protected AbstractCurveFitter(int n,
+                                int maxIterations,
+                                double convergence,
+                                double steadyStateThreshold,
+                                double epsilon) {
+
+    coefficients              = new EstimatedParameter[n];
+    measurements              = new ArrayList();
+    measurementsArray         = null;
+    this.maxIterations        = maxIterations;
+    this.steadyStateThreshold = steadyStateThreshold;
+    this.convergence          = convergence;
+    this.epsilon              = epsilon;
+
+  }
+
+  /**
+   * Simple constructor.
+   * @param coefficients first estimate of the coefficients. A
+   * reference to this array is hold by the newly created object. Its
+   * elements will be adjusted during the fitting process and they will
+   * be set to the adjusted coefficients at the end.
+   * @param maxIterations maximum number of iterations allowed
+   * @param convergence criterion threshold below which we do not need
+   * to improve the criterion anymore
+   * @param steadyStateThreshold steady state detection threshold, the
+   * problem has reached a steady state (read converged) if
+   * <code>Math.abs (Jn - Jn-1) < Jn * convergence</code>, where
+   * <code>Jn</code> and <code>Jn-1</code> are the current and
+   * preceding criterion value (square sum of the weighted residuals
+   * of considered measurements).
+   * @param epsilon threshold under which the matrix of the linearized
+   * problem is considered singular (see {@link
+   * org.spaceroots.mantissa.linalg.SquareMatrix#solve(
+   * org.spaceroots.mantissa.linalg.Matrix,double) SquareMatrix.solve}).
+   */
+  protected AbstractCurveFitter(EstimatedParameter[] coefficients,
+                                int maxIterations,
+                                double convergence,
+                                double steadyStateThreshold,
+                                double epsilon) {
+
+    this.coefficients         = coefficients;
+    measurements              = new ArrayList();
+    measurementsArray         = null;
+    this.maxIterations        = maxIterations;
+    this.steadyStateThreshold = steadyStateThreshold;
+    this.convergence          = convergence;
+    this.epsilon              = epsilon;
+  }
+
+  /** Add a weighted (x,y) pair to the sample.
+   * @param weight weight of this pair in the fit
+   * @param x      abscissa
+   * @param y      ordinate, we have <code>y = f (x)</code>
+   */
+  public void addWeightedPair(double weight, double x, double y) {
+    measurementsArray = null;
+    measurements.add(new FitMeasurement(weight, x, y));
+  }
+
+  /** Perform the fitting.
+
+   * <p>This method compute the coefficients of the curve that best
+   * fit the sample of weighted pairs previously given through calls
+   * to the {@link #addWeightedPair addWeightedPair} method.</p>
+
+   * @return coefficients of the curve
+   * @exception EstimationException if the fitting is not possible
+   * (for example if the sample has to few independant points)
+
+   */
+  public double[] fit()
+    throws EstimationException {
+    // perform the fit using a linear least square estimator
+    new GaussNewtonEstimator(maxIterations, convergence,
+                             steadyStateThreshold, epsilon).estimate(this);
+
+    // extract the coefficients
+    double[] fittedCoefficients = new double[coefficients.length];
+    for (int i = 0; i < coefficients.length; ++i) {
+      fittedCoefficients[i] = coefficients[i].getEstimate();
+    }
+
+    return fittedCoefficients;
+
+  }
+
+  public WeightedMeasurement[] getMeasurements() {
+    if (measurementsArray == null) {
+      measurementsArray = new FitMeasurement[measurements.size()];
+      int i = 0;
+      for (Iterator iterator = measurements.iterator(); iterator.hasNext(); ++i) {
+        measurementsArray[i] = (FitMeasurement) iterator.next();
+      }
+    }
+    return measurementsArray;
+  }
+
+  /** Get the unbound parameters of the problem.
+   * For a curve fitting, none of the function coefficient is bound.
+   * @return unbound parameters
+   */
+  public EstimatedParameter[] getUnboundParameters() {
+   return coefficients;
+  }
+
+  /** Get all the parameters of the problem.
+   * @return parameters
+   */
+  public EstimatedParameter[] getAllParameters() {
+   return coefficients;
+  }
+
+  /** Utility method to sort the measurements with respect to the abscissa.
+
+   * <p>This method is provided as a utility for derived classes. As
+   * an example, the {@link HarmonicFitter} class needs it in order to
+   * compute a first guess of the coefficients to initialize the
+   * estimation algorithm.</p>
+
+   */
+  protected void sortMeasurements() {
+
+    // Since the samples are almost always already sorted, this
+    // method is implemented as an insertion sort that reorders the
+    // elements in place. Insertion sort is very efficient in this case.
+    FitMeasurement curr = (FitMeasurement) measurements.get(0);
+    for (int j = 1; j < measurements.size (); ++j) {
+      FitMeasurement prec = curr;
+      curr = (FitMeasurement) measurements.get(j);
+      if (curr.x < prec.x) {
+        // the current element should be inserted closer to the beginning
+        int i = j - 1;
+        FitMeasurement mI = (FitMeasurement) measurements.get(i);
+        while ((i >= 0) && (curr.x < mI.x)) {
+          measurements.set(i + 1, mI);
+          if (i-- != 0) {
+            mI = (FitMeasurement) measurements.get(i);
+          } else {
+            mI = null;
+          }
+        }
+        measurements.set(i + 1, curr);
+        curr = (FitMeasurement) measurements.get(j);
+      }
+    }
+
+    // make sure subsequent calls to getMeasurements
+    // will not use the unsorted array
+    measurementsArray = null;
+
+  }
+
+  /** Get the value of the function at x according to the current parameters value.
+   * @param x abscissa at which the theoretical value is requested
+   * @return theoretical value at x
+   */
+  public abstract double valueAt(double x);
+
+  /** Get the derivative of the function at x with respect to parameter p.
+   * @param x abscissa at which the partial derivative is requested
+   * @param p parameter with respect to which the derivative is requested
+   * @return partial derivative
+   */
+  public abstract double partial(double x, EstimatedParameter p);
+
+  /** This class represents the fit measurements.
+   * One measurement is a weighted pair (x, y), where <code>y = f
+   * (x)</code> is the value of the function at x abscissa. This class
+   * is an inner class because the methods related to the computation
+   * of f values and derivative are proveded by the fitter
+   * implementations.
+   */
+  public class FitMeasurement
+    extends WeightedMeasurement {
+
+    /** Simple constructor.
+     * @param weight weight of the measurement in the fitting process
+     * @param x abscissa of the measurement
+     * @param y ordinate of the measurement
+     */
+    public FitMeasurement(double weight, double x, double y) {
+      super(weight, y);
+      this.x = x;
+    }
+
+    /** Get the value of the fitted function at x.
+     * @return theoretical value at the measurement abscissa
+     */
+    public double getTheoreticalValue() {
+      return valueAt(x);
+    }
+
+    /** Partial derivative with respect to one function coefficient.
+     * @param p parameter with respect to which the derivative is requested
+     * @return partial derivative
+     */
+    public double getPartial(EstimatedParameter p) {
+     return partial(x, p);
+    }
+
+    /** Abscissa of the measurement. */
+    public final double x;
+
+    private static final long serialVersionUID = -2682582852369995960L;
+
+  }
+
+  /** Coefficients of the function */
+  protected EstimatedParameter[] coefficients;
+
+  /** Measurements vector */
+  protected List measurements;
+
+  /** Measurements array.
+   * This array contains the same entries as measurements_, but in a
+   * different structure.
+   */
+  private FitMeasurement[] measurementsArray;
+
+  private int    maxIterations;
+  private double convergence;
+  private double steadyStateThreshold;
+  private double epsilon;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/AbstractCurveFitter.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/F2FP2Iterator.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/F2FP2Iterator.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/F2FP2Iterator.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/F2FP2Iterator.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,74 @@
+// 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.spaceroots.mantissa.fitting;
+
+import java.io.Serializable;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+import org.spaceroots.mantissa.functions.ExhaustedSampleException;
+import org.spaceroots.mantissa.functions.vectorial.SampledFunctionIterator;
+import org.spaceroots.mantissa.functions.vectorial.VectorialValuedPair;
+
+/** This class provides sampled values of the function t -> [f(t)^2, f'(t)^2].
+
+ * This class is a helper class used to compute a first guess of the
+ * harmonic coefficients of a function <code>f (t) = a cos (omega t +
+ * phi)</code>.
+
+ * @see FFPIterator
+ * @see HarmonicCoefficientsGuesser
+
+ * @version $Id: F2FP2Iterator.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+
+class F2FP2Iterator
+  implements SampledFunctionIterator, Serializable {
+
+  public F2FP2Iterator(AbstractCurveFitter.FitMeasurement[] measurements) {
+    ffpIterator = new FFPIterator(measurements);
+  }
+
+  public int getDimension() {
+    return 2;
+  }
+
+  public boolean hasNext() {
+    return ffpIterator.hasNext();
+  }
+
+  public VectorialValuedPair nextSamplePoint()
+    throws ExhaustedSampleException, FunctionException {
+
+    // get the raw values from the underlying FFPIterator
+    VectorialValuedPair point = ffpIterator.nextSamplePoint();
+
+    // hack the values (to avoid building a new object)
+    double[] y = point.getY();
+    y[0] *= y[0];
+    y[1] *= y[1];
+    return point;
+
+  }
+
+  private FFPIterator ffpIterator;
+
+  private static final long serialVersionUID = -8113110433795298072L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/F2FP2Iterator.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/FFPIterator.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/FFPIterator.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/FFPIterator.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/FFPIterator.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,100 @@
+// 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.spaceroots.mantissa.fitting;
+
+import java.io.Serializable;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+import org.spaceroots.mantissa.functions.ExhaustedSampleException;
+import org.spaceroots.mantissa.functions.vectorial.SampledFunctionIterator;
+import org.spaceroots.mantissa.functions.vectorial.VectorialValuedPair;
+
+/** This class provides sampled values of the function t -> [f(t), f'(t)].
+
+ * This class is a helper class used to compute a first guess of the
+ * harmonic coefficients of a function <code>f (t) = a cos (omega t +
+ * phi)</code>.
+
+ * @see F2FP2Iterator
+ * @see HarmonicCoefficientsGuesser
+
+ * @version $Id: FFPIterator.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+
+class FFPIterator
+  implements SampledFunctionIterator, Serializable {
+
+  public FFPIterator(AbstractCurveFitter.FitMeasurement[] measurements) {
+    this.measurements = measurements;
+
+    // initialize the points of the raw sample
+    current   = measurements[0];
+    currentY  = current.getMeasuredValue();
+    next      = measurements[1];
+    nextY     = next.getMeasuredValue();
+    nextIndex = 2;
+
+  }
+
+  public int getDimension() {
+    return 2;
+  }
+
+  public boolean hasNext() {
+    return nextIndex < measurements.length;
+  }
+
+  public VectorialValuedPair nextSamplePoint()
+    throws ExhaustedSampleException, FunctionException {
+    if (nextIndex >= measurements.length) {
+      throw new ExhaustedSampleException(measurements.length);
+    }
+
+    // shift the points
+    previous  = current;
+    previousY = currentY;
+    current   = next;
+    currentY  = nextY;
+    next      = measurements[nextIndex++];
+    nextY     = next.getMeasuredValue();
+
+    // return the two dimensions vector [f(x), f'(x)]
+    double[] table = new double[2];
+    table[0] = currentY;
+    table[1] = (nextY - previousY) / (next.x - previous.x);
+    return new VectorialValuedPair(current.x, table);
+
+  }
+
+  private AbstractCurveFitter.FitMeasurement[] measurements;
+  private int nextIndex;
+
+  private AbstractCurveFitter.FitMeasurement previous;
+  private double previousY;
+
+  private AbstractCurveFitter.FitMeasurement current;
+  private double nextY;
+
+  private AbstractCurveFitter.FitMeasurement next;
+  private double currentY;
+
+  private static final long serialVersionUID = -3187229691615380125L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/FFPIterator.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicCoefficientsGuesser.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicCoefficientsGuesser.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicCoefficientsGuesser.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicCoefficientsGuesser.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,271 @@
+// 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.spaceroots.mantissa.fitting;
+
+import java.io.Serializable;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+import org.spaceroots.mantissa.functions.ExhaustedSampleException;
+import org.spaceroots.mantissa.functions.vectorial.SampledFunctionIterator;
+import org.spaceroots.mantissa.functions.vectorial.VectorialValuedPair;
+
+import org.spaceroots.mantissa.quadrature.vectorial.EnhancedSimpsonIntegratorSampler;
+
+import org.spaceroots.mantissa.estimation.EstimationException;
+
+/** This class guesses harmonic coefficients from a sample.
+
+ * <p>The algorithm used to guess the coefficients is as follows:</p>
+
+ * <p>We know f (t) at some sampling points ti and want to find a,
+ * omega and phi such that f (t) = a cos (omega t + phi).
+ * </p>
+ *
+ * <p>From the analytical expression, we can compute two primitives :
+ * <pre>
+ *     If2  (t) = int (f^2)  = a^2 * [t + S (t)] / 2
+ *     If'2 (t) = int (f'^2) = a^2 * omega^2 * [t - S (t)] / 2
+ *     where S (t) = sin (2 * (omega * t + phi)) / (2 * omega)
+ * </pre>
+ * </p>
+ *
+ * <p>We can remove S between these expressions :
+ * <pre>
+ *     If'2 (t) = a^2 * omega ^ 2 * t - omega ^ 2 * If2 (t)
+ * </pre>
+ * </p>
+ *
+ * <p>The preceding expression shows that If'2 (t) is a linear
+ * combination of both t and If2 (t): If'2 (t) = A * t + B * If2 (t)
+ * </p>
+ *
+ * <p>From the primitive, we can deduce the same form for definite
+ * integrals between t1 and ti for each ti :
+ * <pre>
+ *   If2 (ti) - If2 (t1) = A * (ti - t1) + B * (If2 (ti) - If2 (t1))
+ * </pre>
+ * </p>
+ *
+ * <p>We can find the coefficients A and B that best fit the sample
+ * to this linear expression by computing the definite integrals for
+ * each sample points.
+ * </p>
+ *
+ * <p>For a bilinear expression z (xi, yi) = A * xi + B * yi, the
+ * coefficients a and b that minimize a least square criterion
+ * Sum ((zi - z (xi, yi))^2) are given by these expressions:</p>
+ * <pre>
+ *
+ *         Sum (yi^2) Sum (xi zi) - Sum (xi yi) Sum (yi zi)
+ *     A = ------------------------------------------------
+ *         Sum (xi^2) Sum (yi^2)  - Sum (xi yi) Sum (xi yi)
+ *
+ *         Sum (xi^2) Sum (yi zi) - Sum (xi yi) Sum (xi zi)
+ *     B = ------------------------------------------------
+ *         Sum (xi^2) Sum (yi^2)  - Sum (xi yi) Sum (xi yi)
+ * </pre>
+ * </p>
+ *
+ *
+ * <p>In fact, we can assume both a and omega are positive and
+ * compute them directly, knowing that A = a^2 * omega^2 and that
+ * B = - omega^2. The complete algorithm is therefore:</p>
+ * <pre>
+ *
+ * for each ti from t1 to t(n-1), compute:
+ *   f  (ti)
+ *   f' (ti) = (f (t(i+1)) - f(t(i-1))) / (t(i+1) - t(i-1))
+ *   xi = ti - t1
+ *   yi = int (f^2) from t1 to ti
+ *   zi = int (f'^2) from t1 to ti
+ *   update the sums Sum (xi^2), Sum (yi^2),
+ *                   Sum (xi yi), Sum (xi zi)
+ *                   and Sum (yi zi)
+ * end for
+ *
+ *            |-------------------------------------------------
+ *         \  | Sum (yi^2) Sum (xi zi) - Sum (xi yi) Sum (yi zi)
+ * a     =  \ | ------------------------------------------------
+ *           \| Sum (xi yi) Sum (xi zi) - Sum (xi^2) Sum (yi zi)
+ *
+ *
+ *            |-------------------------------------------------
+ *         \  | Sum (xi yi) Sum (xi zi) - Sum (xi^2) Sum (yi zi)
+ * omega =  \ | ------------------------------------------------
+ *           \| Sum (xi^2) Sum (yi^2)  - Sum (xi yi) Sum (xi yi)
+ *
+ * </pre>
+ * </p>
+
+ * <p>Once we know omega, we can compute:
+ * <pre>
+ *    fc = omega * f (t) * cos (omega * t) - f' (t) * sin (omega * t)
+ *    fs = omega * f (t) * sin (omega * t) + f' (t) * cos (omega * t)
+ * </pre>
+ * </p>
+
+ * <p>It appears that <code>fc = a * omega * cos (phi)</code> and
+ * <code>fs = -a * omega * sin (phi)</code>, so we can use these
+ * expressions to compute phi. The best estimate over the sample is
+ * given by averaging these expressions.
+ * </p>
+
+ * <p>Since integrals and means are involved in the preceding
+ * estimations, these operations run in O(n) time, where n is the
+ * number of measurements.</p>
+
+ * @version $Id: HarmonicCoefficientsGuesser.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+
+public class HarmonicCoefficientsGuesser
+  implements Serializable{
+
+  public HarmonicCoefficientsGuesser(AbstractCurveFitter.FitMeasurement[] measurements) {
+    this.measurements = measurements;
+    a                 = Double.NaN;
+    omega             = Double.NaN;
+  }
+
+  /** Estimate a first guess of the coefficients.
+
+   * @exception ExhaustedSampleException if the sample is exhausted.
+
+   * @exception FunctionException if the integrator throws one.
+
+   * @exception EstimationException if the sample is too short or if
+   * the first guess cannot be computed (when the elements under the
+   * square roots are negative).
+   * */
+  public void guess()
+    throws ExhaustedSampleException, FunctionException, EstimationException {
+    guessAOmega();
+    guessPhi();
+  }
+
+  /** Estimate a first guess of the a and omega coefficients.
+
+   * @exception ExhaustedSampleException if the sample is exhausted.
+
+   * @exception FunctionException if the integrator throws one.
+
+   * @exception EstimationException if the sample is too short or if
+   * the first guess cannot be computed (when the elements under the
+   * square roots are negative).
+
+   */
+  private void guessAOmega()
+    throws ExhaustedSampleException, FunctionException, EstimationException {
+
+    // initialize the sums for the linear model between the two integrals
+    double sx2 = 0.0;
+    double sy2 = 0.0;
+    double sxy = 0.0;
+    double sxz = 0.0;
+    double syz = 0.0;
+
+    // build the integrals sampler
+    F2FP2Iterator iter = new F2FP2Iterator(measurements);
+    SampledFunctionIterator sampler =
+      new EnhancedSimpsonIntegratorSampler(iter);
+    VectorialValuedPair p0 = sampler.nextSamplePoint();
+    double   p0X = p0.getX();
+    double[] p0Y = p0.getY();
+
+    // get the points for the linear model
+    while (sampler.hasNext()) {
+
+      VectorialValuedPair point = sampler.nextSamplePoint();
+      double   pX = point.getX();
+      double[] pY = point.getY();
+
+      double dx  = pX    - p0X;
+      double dy0 = pY[0] - p0Y[0];
+      double dy1 = pY[1] - p0Y[1];
+
+      sx2 += dx  * dx;
+      sy2 += dy0 * dy0;
+      sxy += dx  * dy0;
+      sxz += dx  * dy1;
+      syz += dy0 * dy1;
+
+    }
+
+    // compute the amplitude and pulsation coefficients
+    double c1 = sy2 * sxz - sxy * syz;
+    double c2 = sxy * sxz - sx2 * syz;
+    double c3 = sx2 * sy2 - sxy * sxy;
+    if ((c1 / c2 < 0.0) || (c2 / c3 < 0.0)) {
+      throw new EstimationException("unable to guess a first estimate");
+    }
+    a     = Math.sqrt(c1 / c2);
+    omega = Math.sqrt(c2 / c3);
+
+  }
+
+  /** Estimate a first guess of the phi coefficient.
+
+   * @exception ExhaustedSampleException if the sample is exhausted.
+
+   * @exception FunctionException if the sampler throws one.
+
+   */
+  private void guessPhi()
+    throws ExhaustedSampleException, FunctionException {
+
+    SampledFunctionIterator iter = new FFPIterator(measurements);
+
+    // initialize the means
+    double fcMean = 0.0;
+    double fsMean = 0.0;
+
+    while (iter.hasNext()) {
+      VectorialValuedPair point = iter.nextSamplePoint();
+      double   omegaX = omega * point.getX();
+      double[] pY     = point.getY();
+      double   cosine = Math.cos(omegaX);
+      double   sine   = Math.sin(omegaX);
+      fcMean += omega * pY[0] * cosine - pY[1] *   sine;
+      fsMean += omega * pY[0] *   sine + pY[1] * cosine;
+    }
+
+    phi = Math.atan2(-fsMean, fcMean);
+
+  }
+
+  public double getOmega() {
+    return omega;
+  }
+
+  public double getA() {
+    return a;
+  }
+
+  public double getPhi() {
+    return phi;
+  }
+
+  private AbstractCurveFitter.FitMeasurement[] measurements;
+  private double a;
+  private double omega;
+  private double phi;
+
+  private static final long serialVersionUID = 2400399048702758814L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicCoefficientsGuesser.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicFitter.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicFitter.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicFitter.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicFitter.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,197 @@
+// 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.spaceroots.mantissa.fitting;
+
+import java.io.Serializable;
+
+import org.spaceroots.mantissa.estimation.*;
+import org.spaceroots.mantissa.functions.ExhaustedSampleException;
+import org.spaceroots.mantissa.functions.FunctionException;
+
+/** This class implements a curve fitting specialized for sinusoids.
+
+ * <p>Harmonic fitting is a very simple case of curve fitting. The
+ * estimated coefficients are the amplitude a, the pulsation omega and
+ * the phase phi: <code>f (t) = a cos (omega t + phi)</code>. They are
+ * searched by a least square estimator initialized with a rough guess
+ * based on integrals.</p>
+
+ * <p>This class <emph>is by no means optimized</emph>, neither versus
+ * space nor versus time performance.</p>
+
+ * @version $Id: HarmonicFitter.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+
+public class HarmonicFitter
+  extends AbstractCurveFitter
+  implements EstimationProblem, Serializable {
+
+  /**
+   * Simple constructor.
+   * @param maxIterations maximum number of iterations allowed
+   * @param convergence criterion threshold below which we do not need
+   * to improve the criterion anymore
+   * @param steadyStateThreshold steady state detection threshold, the
+   * problem has reached a steady state (read converged) if
+   * <code>Math.abs (Jn - Jn-1) < Jn * convergence</code>, where
+   * <code>Jn</code> and <code>Jn-1</code> are the current and
+   * preceding criterion value (square sum of the weighted residuals
+   * of considered measurements).
+   * @param epsilon threshold under which the matrix of the linearized
+   * problem is considered singular (see {@link
+   * org.spaceroots.mantissa.linalg.SquareMatrix#solve(
+   * org.spaceroots.mantissa.linalg.Matrix,double) SquareMatrix.solve}).
+   */
+  public HarmonicFitter(int maxIterations, double convergence,
+                        double steadyStateThreshold, double epsilon) {
+    super(3, maxIterations, convergence, steadyStateThreshold, epsilon);
+    coefficients[0]  = new EstimatedParameter("a", 2.0 * Math.PI);
+    coefficients[1]  = new EstimatedParameter("omega", 0.0);
+    coefficients[2]  = new EstimatedParameter("phi", 0.0);
+    firstGuessNeeded = true;
+  }
+
+  /**
+   * Simple constructor.
+
+   * <p>This constructor can be used when a first estimate of the
+   * coefficients is already known.</p>
+
+   * @param coefficients first estimate of the coefficients.
+   * A reference to this array is hold by the newly created
+   * object. Its elements will be adjusted during the fitting process
+   * and they will be set to the adjusted coefficients at the end.
+   * @param maxIterations maximum number of iterations allowed
+   * @param convergence criterion threshold below which we do not need
+   * to improve the criterion anymore
+   * @param steadyStateThreshold steady state detection threshold, the
+   * problem has reached a steady state (read converged) if
+   * <code>Math.abs (Jn - Jn-1) < Jn * convergence</code>, where
+   * <code>Jn</code> and <code>Jn-1</code> are the current and
+   * preceding criterion value (square sum of the weighted residuals
+   * of considered measurements).
+   * @param epsilon threshold under which the matrix of the linearized
+   * problem is considered singular (see {@link
+   * org.spaceroots.mantissa.linalg.SquareMatrix#solve(
+   * org.spaceroots.mantissa.linalg.Matrix,double) SquareMatrix.solve}).
+
+   */
+  public HarmonicFitter(EstimatedParameter[] coefficients,
+                        int maxIterations, double convergence,
+                        double steadyStateThreshold, double epsilon) {
+    super(coefficients,
+          maxIterations, convergence,
+          steadyStateThreshold, epsilon);
+    firstGuessNeeded = false;
+  }
+
+  public double[] fit()
+    throws EstimationException {
+    if (firstGuessNeeded) {
+      if (measurements.size() < 4) {
+        throw new EstimationException("sample must contain at least {0} points",
+                                      new String[] {
+                                        Integer.toString(4)
+                                      });
+      }
+
+      sortMeasurements();
+
+      try {
+        HarmonicCoefficientsGuesser guesser =
+          new HarmonicCoefficientsGuesser((FitMeasurement[]) getMeasurements());
+        guesser.guess();
+
+        coefficients[0].setEstimate(guesser.getA());
+        coefficients[1].setEstimate(guesser.getOmega());
+        coefficients[2].setEstimate(guesser.getPhi());
+      } catch(ExhaustedSampleException e) {
+        throw new EstimationException(e);
+      } catch(FunctionException e) {
+        throw new EstimationException(e);
+      }
+
+      firstGuessNeeded = false;
+
+    }
+
+    return super.fit();
+
+  }
+
+  /** Get the current amplitude coefficient estimate.
+   * Get a, where <code>f (t) = a cos (omega t + phi)</code>
+   * @return current amplitude coefficient estimate
+   */
+  public double getAmplitude() {
+    return coefficients[0].getEstimate();
+  }
+
+  /** Get the current pulsation coefficient estimate.
+   * Get omega, where <code>f (t) = a cos (omega t + phi)</code>
+   * @return current pulsation coefficient estimate
+   */
+  public double getPulsation() {
+    return coefficients[1].getEstimate();
+  }
+
+  /** Get the current phase coefficient estimate.
+   * Get phi, where <code>f (t) = a cos (omega t + phi)</code>
+   * @return current phase coefficient estimate
+   */
+  public double getPhase() {
+    return coefficients[2].getEstimate();
+  }
+
+  /** Get the value of the function at x according to the current parameters value.
+   * @param x abscissa at which the theoretical value is requested
+   * @return theoretical value at x
+   */
+  public double valueAt(double x) {
+    double a     = coefficients[0].getEstimate();
+    double omega = coefficients[1].getEstimate();
+    double phi   = coefficients[2].getEstimate();
+    return a * Math.cos(omega * x + phi);
+  }
+
+  /** Get the derivative of the function at x with respect to parameter p.
+   * @param x abscissa at which the partial derivative is requested
+   * @param p parameter with respect to which the derivative is requested
+   * @return partial derivative
+   */
+  public double partial(double x, EstimatedParameter p) {
+    double a     = coefficients[0].getEstimate();
+    double omega = coefficients[1].getEstimate();
+    double phi   = coefficients[2].getEstimate();
+    if (p == coefficients[0]) {
+      return Math.cos(omega * x + phi);
+    } else if (p == coefficients[1]) {
+      return -a * x * Math.sin(omega * x + phi);
+    } else {
+      return -a * Math.sin(omega * x + phi);
+    }
+  }
+
+  /** Indicator of the need to compute a first guess of the coefficients. */
+  private boolean firstGuessNeeded;
+
+  private static final long serialVersionUID = -8722683066277473450L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/HarmonicFitter.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialCoefficient.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialCoefficient.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialCoefficient.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialCoefficient.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,44 @@
+// 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.spaceroots.mantissa.fitting;
+
+import org.spaceroots.mantissa.estimation.EstimatedParameter;
+
+/** This class represents a polynomial coefficient.
+
+ * <p>Each coefficient is uniquely defined by its degree.</p>
+
+ * @see PolynomialFitter
+
+ * @version $Id: PolynomialCoefficient.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public class PolynomialCoefficient
+  extends EstimatedParameter {
+
+  public PolynomialCoefficient(int degree) {
+    super("a" + degree, 0.0);
+    this.degree = degree;
+  }
+
+  public final int degree;
+
+  private static final long serialVersionUID = 5775845068390259552L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialCoefficient.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialFitter.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialFitter.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialFitter.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialFitter.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,143 @@
+// 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.spaceroots.mantissa.fitting;
+
+import java.io.Serializable;
+
+import org.spaceroots.mantissa.estimation.*;
+
+/** This class implements a curve fitting specialized for polynomials.
+
+ * <p>Polynomial fitting is a very simple case of curve fitting. The
+ * estimated coefficients are the polynom coefficients. They are
+ * searched by a least square estimator.</p>
+
+ * <p>This class <emph>is by no means optimized</emph>, neither in
+ * space nor in time performance.</p>
+
+ * @see PolynomialCoefficient
+
+ * @version $Id: PolynomialFitter.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+
+public class PolynomialFitter
+  extends AbstractCurveFitter
+  implements EstimationProblem, Serializable {
+
+  /**
+   * Simple constructor.
+
+   * <p>The polynomial fitter built this way are complete polynoms,
+   * ie. a n-degree polynom has n+1 coefficients. In order to build
+   * fitter for sparse polynoms (for example <code>a x^20 - b
+   * x^30</code>, on should first build the coefficients array and
+   * provide it to {@link
+   * #PolynomialFitter(PolynomialCoefficient[], int, double, double,
+   * double)}.</p>
+   * @param degree maximal degree of the polynom
+   * @param maxIterations maximum number of iterations allowed
+   * @param convergence criterion threshold below which we do not need
+   * to improve the criterion anymore
+   * @param steadyStateThreshold steady state detection threshold, the
+   * problem has reached a steady state (read converged) if
+   * <code>Math.abs (Jn - Jn-1) < Jn * convergence</code>, where
+   * <code>Jn</code> and <code>Jn-1</code> are the current and
+   * preceding criterion value (square sum of the weighted residuals
+   * of considered measurements).
+   * @param epsilon threshold under which the matrix of the linearized
+   * problem is considered singular (see {@link
+   * org.spaceroots.mantissa.linalg.SquareMatrix#solve(
+   * org.spaceroots.mantissa.linalg.Matrix,double) SquareMatrix.solve}).
+ 
+   */
+  public PolynomialFitter(int degree,
+                          int maxIterations, double convergence,
+                          double steadyStateThreshold, double epsilon) {
+
+    super(degree + 1,
+          maxIterations, steadyStateThreshold,
+          convergence, epsilon);
+
+    for (int i = 0; i < coefficients.length; ++i) {
+      coefficients[i] = new PolynomialCoefficient(i);
+    }
+
+  }
+
+  /**
+   * Simple constructor.
+
+   * <p>This constructor can be used either when a first estimate of
+   * the coefficients is already known (which is of little interest
+   * because the fit cost is the same whether a first guess is known or
+   * not) or when one needs to handle sparse polynoms like <code>a
+   * x^20 - b x^30</code>.</p>
+
+   * @param coefficients first estimate of the coefficients.
+   * A reference to this array is hold by the newly created
+   * object. Its elements will be adjusted during the fitting process
+   * and they will be set to the adjusted coefficients at the end.
+   * @param maxIterations maximum number of iterations allowed
+   * @param convergence criterion threshold below which we do not need
+   * to improve the criterion anymore
+   * @param steadyStateThreshold steady state detection threshold, the
+   * problem has reached a steady state (read converged) if
+   * <code>Math.abs (Jn - Jn-1) < Jn * convergence</code>, where
+   * <code>Jn</code> and <code>Jn-1</code> are the current and
+   * preceding criterion value (square sum of the weighted residuals
+   * of considered measurements).
+   * @param epsilon threshold under which the matrix of the linearized
+   * problem is considered singular (see {@link
+   * org.spaceroots.mantissa.linalg.SquareMatrix#solve(
+   * org.spaceroots.mantissa.linalg.Matrix,double) SquareMatrix.solve}).
+
+   */
+  public PolynomialFitter(PolynomialCoefficient[] coefficients,
+                          int maxIterations, double convergence,
+                          double steadyStateThreshold, double epsilon) {
+    super(coefficients,
+          maxIterations, steadyStateThreshold,
+          convergence, epsilon);
+  }
+
+  /** Get the value of the function at x according to the current parameters value.
+   * @param x abscissa at which the theoretical value is requested
+   * @return theoretical value at x
+   */
+  public double valueAt(double x) {
+    double y = coefficients[coefficients.length - 1].getEstimate();
+    for (int i = coefficients.length - 2; i >= 0; --i) {
+      y = y * x + coefficients[i].getEstimate();
+    }
+    return y;
+  }
+
+  /** Get the derivative of the function at x with respect to parameter p.
+   * @param x abscissa at which the partial derivative is requested
+   * @param p parameter with respect to which the derivative is requested
+   * @return partial derivative
+   */
+  public double partial(double x, EstimatedParameter p) {
+    return Math.pow(x, ((PolynomialCoefficient) p).degree);
+  }
+
+  private static final long serialVersionUID = -226724596015163603L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/PolynomialFitter.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/doc-files/org_spaceroots_mantissa_fitting_classes.png
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/doc-files/org_spaceroots_mantissa_fitting_classes.png?view=auto&rev=476930
==============================================================================
Binary file - no diff available.

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/doc-files/org_spaceroots_mantissa_fitting_classes.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/package.html
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/package.html?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/package.html (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/package.html Sun Nov 19 13:36:15 2006
@@ -0,0 +1,26 @@
+<html>
+<body>
+This package provides classes to perform curve fitting.
+
+<p>Curve fitting is a special case of an {@link
+org.spaceroots.mantissa.estimation.EstimationProblem estimation problem}
+were the parameters are the coefficients of a function <code>f</code>
+whose graph <code>y=f(x)</code> should pass through sample points, and
+were the measurements are the ordinates of the curve
+<code>yi=f(xi)</code>.</p>
+
+<p>The organisation of this package is explained in the class diagram
+below. The {@link org.spaceroots.mantissa.fitting.AbstractCurveFitter
+AbstractCurveFitter} class is the base class for all curve fitting
+classes, it handles all common features like sample points
+handling. Each specific curve fitting class should sub-class this
+abstract class and implement the {@link
+org.spaceroots.mantissa.fitting.AbstractCurveFitter#valueAt valueAt} and
+{@link org.spaceroots.mantissa.fitting.AbstractCurveFitter#partial
+partial} methods.</p>
+
+<img src="doc-files/org_spaceroots_mantissa_fitting_classes.png" />
+
+@author L. Maisonobe
+</body>
+</html>

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/fitting/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/ExhaustedSampleException.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/ExhaustedSampleException.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/ExhaustedSampleException.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/ExhaustedSampleException.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,42 @@
+// 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.spaceroots.mantissa.functions;
+
+import org.spaceroots.mantissa.MantissaException;
+
+/** This class represents exceptions thrown by sample iterators.
+
+ * @version $Id: ExhaustedSampleException.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+
+public class ExhaustedSampleException
+  extends MantissaException {
+
+  /** Simple constructor.
+   * @param size size of the sample
+   */
+  public ExhaustedSampleException(int size) {
+    super("sample contains only {0} elements",
+          new String[] { Integer.toString(size) });
+  }
+
+  private static final long serialVersionUID = -1490493298938282440L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/ExhaustedSampleException.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/FunctionException.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/FunctionException.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/FunctionException.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/FunctionException.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,59 @@
+// 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.spaceroots.mantissa.functions;
+
+import org.spaceroots.mantissa.MantissaException;
+
+/** This class represents exceptions thrown by scalar functions.
+
+ * @version $Id: FunctionException.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+
+public class FunctionException
+  extends MantissaException {
+
+  /** Simple constructor.
+   * Build an exception by translating and formating a message
+   * @param specifier format specifier (to be translated)
+   * @param parts to insert in the format (no translation)
+   */
+  public FunctionException(String specifier, String[] parts) {
+    super(specifier, parts);
+  }
+
+  /** Simple constructor.
+   * Build an exception by translating the specified message
+   * @param message message to translate
+   */
+  public FunctionException(String message) {
+    super(message);
+  }
+
+  /** Simple constructor.
+   * Build an exception from a cause
+   * @param cause cause of this exception
+   */
+  public FunctionException(Throwable cause) {
+    super(cause);
+  }
+
+  private static final long serialVersionUID = 1455885104381976115L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/FunctionException.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/BasicSampledFunctionIterator.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/BasicSampledFunctionIterator.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/BasicSampledFunctionIterator.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/BasicSampledFunctionIterator.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,73 @@
+// 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.spaceroots.mantissa.functions.scalar;
+
+import java.io.Serializable;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+import org.spaceroots.mantissa.functions.ExhaustedSampleException;
+
+/** This class is a simple wrapper allowing to iterate over a
+ * SampledFunction.
+
+ * <p>The basic implementation of the iteration interface does not
+ * perform any transformation on the sample, it only handles a loop
+ * over the underlying sampled function.</p>
+
+ * @see SampledFunction
+
+ * @version $Id: BasicSampledFunctionIterator.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public class BasicSampledFunctionIterator
+  implements SampledFunctionIterator, Serializable {
+
+  /** Underlying sampled function. */
+  private final SampledFunction function;
+
+  /** Next sample element. */
+  private int next;
+
+  /** Simple constructor.
+   * Build an instance from a SampledFunction
+   * @param function smapled function over which we want to iterate
+   */
+  public BasicSampledFunctionIterator(SampledFunction function) {
+    this.function = function;
+    next          = 0;
+  }
+
+  public boolean hasNext() {
+    return next < function.size();
+  }
+
+  public ScalarValuedPair nextSamplePoint()
+    throws ExhaustedSampleException, FunctionException {
+    if (next >= function.size()) {
+      throw new ExhaustedSampleException(function.size());
+    }
+
+    int current = next++;
+    return function.samplePointAt(current);
+
+  }
+
+  private static final long serialVersionUID = -9106690005598356403L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/BasicSampledFunctionIterator.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunction.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunction.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunction.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunction.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,55 @@
+// 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.spaceroots.mantissa.functions.scalar;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+
+/** This interface represents scalar functions of one real variable.
+
+ * <p>This interface should be implemented by all scalar functions
+ * that can be evaluated at any point. This does not imply that an
+ * explicit definition is available, a function given by an implicit
+ * function that should be numerically solved for each point for
+ * example is considered a computable function.</p>
+
+ * <p>The {@link ComputableFunctionSampler} class can be used to
+ * transform classes implementing this interface into classes
+ * implementing the {@link SampledFunction} interface.</p>
+
+ * <p>Several numerical algorithms (Gauss-Legendre integrators for
+ * example) need to choose themselves the evaluation points, so they
+ * can handle only objects that implement this interface.</p>
+
+ * @see org.spaceroots.mantissa.quadrature.scalar.ComputableFunctionIntegrator
+ * @see SampledFunction
+
+ * @version $Id: ComputableFunction.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public interface ComputableFunction {
+
+  /** Get the value of the function at the specified abscissa.
+   * @param x current abscissa
+   * @return function value
+   * @exception FunctionException if something goes wrong
+   */
+  public double valueAt(double x)
+    throws FunctionException;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunction.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunctionSampler.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunctionSampler.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunctionSampler.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunctionSampler.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,146 @@
+// 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.spaceroots.mantissa.functions.scalar;
+
+import java.io.Serializable;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+
+/** This class is a wrapper allowing to sample a
+ * {@link ComputableFunction}.
+
+ * <p>The sample produced is a regular sample. It can be specified by
+ * several means :
+ * <ul>
+ *   <li> from an initial point a step and a number of points</li>
+ *   <li> from a range and a number of points</li>
+ *   <li> from a range and a step between points.</li>
+ * </ul>
+ * In the latter case, the step can optionaly be adjusted in order to
+ * have the last point exactly at the upper bound of the range.</p>
+
+ * <p>The sample points are computed on demand, they are not
+ * stored. This allow to use this method for very large sample with
+ * little memory overhead. The drawback is that if the same sample
+ * points are going to be requested several times, they will be
+ * recomputed each time. In this case, the user should consider
+ * storing the points by some other means.</p>
+
+ * @see ComputableFunction
+
+ * @version $Id: ComputableFunctionSampler.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public class ComputableFunctionSampler
+  implements SampledFunction, Serializable {
+
+  /** Underlying computable function. */
+  private ComputableFunction function;
+
+  /** Beginning abscissa. */
+  private double begin;
+
+  /** Step between points. */
+  private double step;
+
+  /** Total number of points. */
+  private int n;
+
+  /**
+   * Constructor.
+
+   * Build a sample from an {@link ComputableFunction}. Beware of the
+   * classical off-by-one problem !  If you want to have a sample like
+   * this : 0.0, 0.1, 0.2 ..., 1.0, then you should specify step = 0.1
+   * and n = 11 (not n = 10).
+
+   * @param begin beginning of the range (will be the abscissa of the
+   * first point)
+   * @param step step between points
+   * @param n number of points
+
+   */
+  public ComputableFunctionSampler(ComputableFunction function,
+                                   double begin, double step, int n) {
+    this.function = function;
+    this.begin    = begin;
+    this.step     = step;
+    this.n        = n;
+  }
+
+  /**
+   * Constructor.
+   * Build a sample from an {@link ComputableFunction}.
+
+   * @param range abscissa range (from <code>range [0]</code> to
+   * <code>range [1]</code>)
+   * @param n number of points
+   */
+  public ComputableFunctionSampler(ComputableFunction function,
+                                   double[] range, int n) {
+    this.function = function;
+    begin         = range[0];
+    step          = (range[1] - range[0]) / (n - 1);
+    this.n        = n;
+  }
+
+  /**
+   * Constructor.
+   * Build a sample from an {@link ComputableFunction}.
+
+   * @param range abscissa range (from <code>range [0]</code> to
+   * <code>range [1]</code>)
+   * @param step step between points
+   * @param adjustStep if true, the step is reduced in order to have
+   * the last point of the sample exactly at <code>range [1]</code>,
+   * if false the last point will be between <code>range [1] -
+   * step</code> and <code>range [1]</code> */
+  public ComputableFunctionSampler(ComputableFunction function,
+                                   double[] range, double step,
+                                   boolean adjustStep) {
+    this.function = function;
+    begin         = range [0];
+    if (adjustStep) {
+      n         = (int) Math.ceil((range[1] - range[0]) / step);
+      this.step = (range[1] - range[0]) / (n - 1);
+    } else {
+      n         = (int) Math.floor((range[1] - range[0]) / step);
+      this.step = step;
+    }
+  }
+
+  public int size() {
+    return n;
+  }
+
+  public ScalarValuedPair samplePointAt(int index)
+    throws ArrayIndexOutOfBoundsException, FunctionException {
+
+    if (index < 0 || index >= n) {
+      throw new ArrayIndexOutOfBoundsException();
+    }
+
+    double x = begin + index * step;
+    return new ScalarValuedPair(x, function.valueAt(x));
+
+  }
+
+  private static final long serialVersionUID = -5127043442851795719L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ComputableFunctionSampler.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunction.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunction.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunction.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunction.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,66 @@
+// 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.spaceroots.mantissa.functions.scalar;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+
+/** This interface represent sampled scalar functions.
+
+ * <p>A function sample is an ordered set of points of the form (x, y)
+ * where x is the abscissa of the point and y is the function value at
+ * x. It is typically a function that has been computed by external
+ * means or the result of measurements.</p>
+
+ * <p>The {@link ComputableFunctionSampler} class can be used to
+ * transform classes implementing the {@link ComputableFunction}
+ * interface into classes implementing this interface.</p>
+
+ * <p>Sampled functions cannot be directly handled by integrators
+ * implementing the {@link
+ * org.spaceroots.mantissa.quadrature.scalar.SampledFunctionIntegrator
+ * SampledFunctionIntegrator}. These integrators need a {@link
+ * SampledFunctionIterator} object to iterate over the
+ * sample.</p>
+
+ * @see SampledFunctionIterator
+ * @see ComputableFunctionSampler
+ * @see ComputableFunction
+
+ * @version $Id: SampledFunction.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public interface SampledFunction {
+
+  /** Get the number of points in the sample.
+   * @return number of points in the sample
+   */
+  public int size();
+
+  /** Get the abscissa and value of the sample at the specified index.
+   * @param index index in the sample, should be between 0 and
+   * {@link #size} - 1
+   * @return abscissa and value of the sample at the specified index
+   * @exception ArrayIndexOutOfBoundsException if the index is wrong
+   * @exception FunctionException if an eventual underlying function
+   * throws one
+   */
+  public ScalarValuedPair samplePointAt(int index)
+    throws ArrayIndexOutOfBoundsException, FunctionException;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunction.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunctionIterator.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunctionIterator.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunctionIterator.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunctionIterator.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,47 @@
+// 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.spaceroots.mantissa.functions.scalar;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+import org.spaceroots.mantissa.functions.ExhaustedSampleException;
+
+/** This interface provides iteration services over scalar functions
+ * samples.
+
+ * @see SampledFunction
+
+ * @version $Id: SampledFunctionIterator.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public interface SampledFunctionIterator {
+
+  /** Check if the iterator can provide another point.
+   * @return true if the iterator can provide another point.
+   */
+  public boolean hasNext();
+
+  /** Get the next point of a sampled function.
+   * @return the next point of the sampled function
+   * @exception ExhaustedSampleException if the sample has been exhausted
+   * @exception FunctionException if the underlying function throws one
+   */
+  public ScalarValuedPair nextSamplePoint()
+    throws ExhaustedSampleException, FunctionException;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/SampledFunctionIterator.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ScalarValuedPair.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ScalarValuedPair.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ScalarValuedPair.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ScalarValuedPair.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,97 @@
+// 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.spaceroots.mantissa.functions.scalar;
+
+import java.io.Serializable;
+
+/** This class represents an (x, f(x)) pair for scalar functions.
+
+ * <p>A scalar function is a function of one scalar parameter x whose
+ * value is a scalar. This class is used has a simple placeholder to
+ * contain both an abscissa and the value of the function at this
+ * abscissa.</p>
+
+ * @see SampledFunction
+ * @see org.spaceroots.mantissa.functions.vectorial.VectorialValuedPair
+
+ * @version $Id: ScalarValuedPair.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public class ScalarValuedPair
+  implements Serializable {
+
+  /** Simple constructor.
+   * Build an instance from its coordinates
+   * @param x abscissa
+   * @param y ordinate (value of the function)
+   */
+  public ScalarValuedPair(double x, double y) {
+    this.x = x;
+    this.y = y;
+  }
+
+  /** Copy-constructor.
+   * @param p point to copy
+   */
+  public ScalarValuedPair(ScalarValuedPair p) {
+    x = p.x;
+    y = p.y;
+  }
+
+  /**
+   * Getter for the abscissa.
+   * @return value of the abscissa
+   */
+  public double getX() {
+    return x;
+  }
+
+  /**
+   * Getter for the ordinate.
+   * @return value of the ordinate
+   */
+  public double getY() {
+    return y;
+  }
+
+  /**
+   * Setter for the abscissa.
+   * @param x new value for the abscissa
+   */
+  public void setX(double x) {
+    this.x = x;
+  }
+
+  /**
+   * Setter for the ordinate.
+   * @param y new value for the ordinate
+   */
+  public void setY(double y) {
+    this.y = y;
+  }
+
+  /** Abscissa of the point. */
+  private double x;
+
+  /** Scalar ordinate of the point, y = f (x). */
+  private double y;
+
+  private static final long serialVersionUID = 1884346552569300794L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/scalar/ScalarValuedPair.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/BasicSampledFunctionIterator.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/BasicSampledFunctionIterator.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/BasicSampledFunctionIterator.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/BasicSampledFunctionIterator.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,78 @@
+// 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.spaceroots.mantissa.functions.vectorial;
+
+import java.io.Serializable;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+import org.spaceroots.mantissa.functions.ExhaustedSampleException;
+
+/** This class is a wrapper allowing to iterate over a
+ * SampledFunction.
+
+ * <p>The basic implementation of the iteration interface does not
+ * perform any transformation on the sample, it only handles a loop
+ * over the underlying sampled function.</p>
+
+ * @see SampledFunction
+
+ * @version $Id: BasicSampledFunctionIterator.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public class BasicSampledFunctionIterator
+  implements SampledFunctionIterator, Serializable {
+
+  /** Simple constructor.
+   * Build an instance from a SampledFunction
+   * @param function smapled function over which we want to iterate
+   */
+  public BasicSampledFunctionIterator(SampledFunction function) {
+    this.function = function;
+    next          = 0;
+  }
+
+  public int getDimension() {
+    return function.getDimension();
+  }
+
+  public boolean hasNext() {
+    return next < function.size();
+  }
+
+  public VectorialValuedPair nextSamplePoint()
+    throws ExhaustedSampleException, FunctionException {
+
+    if (next >= function.size()) {
+      throw new ExhaustedSampleException(function.size());
+    }
+
+    int current = next++;
+    return function.samplePointAt(current);
+
+  }
+
+  /** Underlying sampled function. */
+  private final SampledFunction function;
+
+  /** Next sample element. */
+  private int next;
+
+  private static final long serialVersionUID = -4386278658288500627L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/BasicSampledFunctionIterator.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunction.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunction.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunction.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunction.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,59 @@
+// 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.spaceroots.mantissa.functions.vectorial;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+
+/** This interface represents vectorial functions of one real variable.
+
+ * <p>This interface should be implemented by all vectorial functions
+ * that can be evaluated at any point. This does not imply that an
+ * explicit definition is available, a function given by an implicit
+ * function that should be numerically solved for each point for
+ * example is considered a computable function.</p>
+
+ * <p>The {@link ComputableFunctionSampler} class can be used to
+ * transform classes implementing this interface into classes
+ * implementing the {@link SampledFunction} interface.</p>
+
+ * <p>Several numerical algorithms (Gauss-Legendre integrators for
+ * example) need to choose themselves the evaluation points, so they
+ * can handle only objects that implement this interface.</p>
+
+ * @see org.spaceroots.mantissa.quadrature.vectorial.ComputableFunctionIntegrator
+ * @see SampledFunction
+
+ * @version $Id: ComputableFunction.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public interface ComputableFunction {
+  /** Get the dimension of the vectorial values of the function.
+   * @return dimension
+   */
+  public int getDimension();
+
+  /** Get the value of the function at the specified abscissa.
+   * @param x current abscissa
+   * @return function value
+   * @exception FunctionException if something goes wrong
+   */
+  public double[] valueAt(double x)
+    throws FunctionException;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunction.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunctionSampler.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunctionSampler.java?view=auto&rev=476930
==============================================================================
--- jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunctionSampler.java (added)
+++ jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunctionSampler.java Sun Nov 19 13:36:15 2006
@@ -0,0 +1,150 @@
+// 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.spaceroots.mantissa.functions.vectorial;
+
+import java.io.Serializable;
+
+import org.spaceroots.mantissa.functions.FunctionException;
+
+/** This class is a wrapper allowing to sample a
+ * {@link ComputableFunction}.
+
+ * <p>The sample produced is a regular sample. It can be specified by
+ * several means :
+ * <ul>
+ *   <li> from an initial point a step and a number of points</li>
+ *   <li> from a range and a number of points</li>
+ *   <li> from a range and a step between points.</li>
+ * </ul>
+ * In the latter case, the step can optionaly be adjusted in order to
+ * have the last point exactly at the upper bound of the range.</p>
+
+ * <p>The sample points are computed on demand, they are not
+ * stored. This allow to use this method for very large sample with
+ * little memory overhead. The drawback is that if the same sample
+ * points are going to be requested several times, they will be
+ * recomputed each time. In this case, the user should consider
+ * storing the points by some other means.</p>
+
+ * @see ComputableFunction
+
+ * @version $Id: ComputableFunctionSampler.java 1705 2006-09-17 19:57:39Z luc $
+ * @author L. Maisonobe
+
+ */
+public class ComputableFunctionSampler
+  implements SampledFunction, Serializable {
+
+  /**
+   * Constructor.
+
+   * Build a sample from an {@link ComputableFunction}. Beware of the
+   * classical off-by-one problem !  If you want to have a sample like
+   * this : 0.0, 0.1, 0.2 ..., 1.0, then you should specify step = 0.1
+   * and n = 11 (not n = 10).
+
+   * @param begin beginning of the range (will be the abscissa of the
+   * first point)
+   * @param step step between points
+   * @param n number of points
+
+   */
+  public ComputableFunctionSampler(ComputableFunction function,
+                                   double begin, double step, int n) {
+    this.function = function;
+    this.begin    = begin;
+    this.step     = step;
+    this.n        = n;
+  }
+
+  /**
+   * Constructor.
+   * Build a sample from an {@link ComputableFunction}.
+
+   * @param range abscissa range (from <code>range [0]</code> to
+   * <code>range [1]</code>)
+   * @param n number of points
+   */
+  public ComputableFunctionSampler(ComputableFunction function,
+                                   double[] range, int n) {
+    this.function = function;
+    begin         = range[0];
+    step          = (range[1] - range[0]) / (n - 1);
+    this.n        = n;
+  }
+
+  /**
+   * Constructor.
+   * Build a sample from an {@link ComputableFunction}.
+
+   * @param range abscissa range (from <code>range [0]</code> to
+   * <code>range [1]</code>)
+   * @param step step between points
+   * @param adjustStep if true, the step is reduced in order to have
+   * the last point of the sample exactly at <code>range [1]</code>,
+   * if false the last point will be between <code>range [1] -
+   * step</code> and <code>range [1]</code> */
+  public ComputableFunctionSampler(ComputableFunction function,
+                                   double[] range, double step,
+                                   boolean adjustStep) {
+    this.function = function;
+    begin         = range[0];
+    if (adjustStep) {
+      n    = (int) Math.ceil((range[1] - range[0]) / step);
+      this.step = (range[1] - range[0]) / (n - 1);
+    } else {
+      n    = (int) Math.floor((range[1] - range[0]) / step);
+      this.step = step;
+    }
+  }
+
+  public int size() {
+    return n;
+  }
+
+  public int getDimension() {
+    return function.getDimension();
+  }
+
+  public VectorialValuedPair samplePointAt(int index)
+    throws ArrayIndexOutOfBoundsException, FunctionException {
+
+    if (index < 0 || index >= n) {
+      throw new ArrayIndexOutOfBoundsException();
+    }
+
+    double x = begin + index * step;
+    return new VectorialValuedPair (x, function.valueAt(x));
+
+  }
+
+  /** Underlying computable function. */
+  private ComputableFunction function;
+
+  /** Beginning abscissa. */
+  private double begin;
+
+  /** Step between points. */
+  private double step;
+
+  /** Total number of points. */
+  private int n;
+
+  private static final long serialVersionUID = 1368582688313212821L;
+
+}

Propchange: jakarta/commons/proper/math/trunk/src/mantissa/src/org/spaceroots/mantissa/functions/vectorial/ComputableFunctionSampler.java
------------------------------------------------------------------------------
    svn:eol-style = native



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message