Mercurial > hg > de.mpg.mpiwg.itgroup.digilib.core
changeset 10:5f2c5fb36e93
commons-math-2.1 added
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/TrajectoryDeterminationProblem.java Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,187 @@ +/* + * 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. + */ + +import org.apache.commons.math.optimization.general.EstimationException; +import org.apache.commons.math.optimization.general.EstimatedParameter; +import org.apache.commons.math.optimization.general.EstimationProblem; +import org.apache.commons.math.optimization.general.LevenbergMarquardtEstimator; +import org.apache.commons.math.optimization.general.SimpleEstimationProblem; +import org.apache.commons.math.optimization.general.WeightedMeasurement; + +public class TrajectoryDeterminationProblem extends SimpleEstimationProblem { + + public static void main(String[] args) { + try { + TrajectoryDeterminationProblem problem = + new TrajectoryDeterminationProblem(0.0, 100.0, 800.0, 1.0, 0.0); + + double[][] distances = { + { 0.0, 806.5849 }, { 20.0, 796.8148 }, { 40.0, 791.0833 }, { 60.0, 789.6712 }, + { 80.0, 793.1334 }, { 100.0, 797.7248 }, { 120.0, 803.2785 }, { 140.0, 813.4939 }, + { 160.0, 826.9295 }, { 180.0, 844.0640 }, { 200.0, 863.3829 }, { 220.0, 883.3143 }, + { 240.0, 908.6867 }, { 260.0, 934.8561 }, { 280.0, 964.0730 }, { 300.0, 992.1033 }, + { 320.0, 1023.998 }, { 340.0, 1057.439 }, { 360.0, 1091.912 }, { 380.0, 1125.968 }, + { 400.0, 1162.789 }, { 420.0, 1201.517 }, { 440.0, 1239.176 }, { 460.0, 1279.347 } }; + for (int i = 0; i < distances.length; ++i) { + problem.addDistanceMeasurement(1.0, distances[i][0], distances[i][1]); + }; + + double[][] angles = { + { 10.0, 1.415423 }, { 30.0, 1.352643 }, { 50.0, 1.289290 }, { 70.0, 1.225249 }, + { 90.0, 1.161203 }, {110.0, 1.098538 }, {130.0, 1.036263 }, {150.0, 0.976052 }, + {170.0, 0.917921 }, {190.0, 0.861830 }, {210.0, 0.808237 }, {230.0, 0.757043 }, + {250.0, 0.708650 }, {270.0, 0.662949 }, {290.0, 0.619903 }, {310.0, 0.579160 }, + {330.0, 0.541033 }, {350.0, 0.505590 }, {370.0, 0.471746 }, {390.0, 0.440155 }, + {410.0, 0.410522 }, {430.0, 0.382701 }, {450.0, 0.356957 }, {470.0, 0.332400 } }; + for (int i = 0; i < angles.length; ++i) { + problem.addAngularMeasurement(3.0e7, angles[i][0], angles[i][1]); + }; + + LevenbergMarquardtEstimator estimator = new LevenbergMarquardtEstimator(); + estimator.estimate(problem); + System.out.println("initial position: " + problem.getX0() + " " + problem.getY0()); + System.out.println("velocity: " + problem.getVx0() + " " + problem.getVy0()); + + } catch (EstimationException ee) { + System.err.println(ee.getMessage()); + } + } + + public TrajectoryDeterminationProblem(double t0, + double x0Guess, double y0Guess, + double vx0Guess, double vy0Guess) { + this.t0 = t0; + x0 = new EstimatedParameter( "x0", x0Guess); + y0 = new EstimatedParameter( "y0", y0Guess); + vx0 = new EstimatedParameter("vx0", vx0Guess); + vy0 = new EstimatedParameter("vy0", vy0Guess); + + // inform the base class about the parameters + addParameter(x0); + addParameter(y0); + addParameter(vx0); + addParameter(vy0); + + } + + public double getX0() { + return x0.getEstimate(); + } + + public double getY0() { + return y0.getEstimate(); + } + + public double getVx0() { + return vx0.getEstimate(); + } + + public double getVy0() { + return vy0.getEstimate(); + } + + public void addAngularMeasurement(double wi, double ti, double ai) { + // let the base class handle the measurement + addMeasurement(new AngularMeasurement(wi, ti, ai)); + } + + public void addDistanceMeasurement(double wi, double ti, double di) { + // let the base class handle the measurement + addMeasurement(new DistanceMeasurement(wi, ti, di)); + } + + public double x(double t) { + return x0.getEstimate() + (t - t0) * vx0.getEstimate(); + } + + public double y(double t) { + return y0.getEstimate() + (t - t0) * vy0.getEstimate(); + } + + private class AngularMeasurement extends WeightedMeasurement { + + public AngularMeasurement(double weight, double t, double angle) { + super(weight, angle); + this.t = t; + } + + public double getTheoreticalValue() { + return Math.atan2(y(t), x(t)); + } + + public double getPartial(EstimatedParameter parameter) { + double xt = x(t); + double yt = y(t); + double r = Math.sqrt(xt * xt + yt * yt); + double u = yt / (r + xt); + double c = 2 * u / (1 + u * u); + if (parameter == x0) { + return -c; + } else if (parameter == vx0) { + return -c * t; + } else if (parameter == y0) { + return c * xt / yt; + } else { + return c * t * xt / yt; + } + } + + private final double t; + private static final long serialVersionUID = -5990040582592763282L; + + } + + private class DistanceMeasurement extends WeightedMeasurement { + + public DistanceMeasurement(double weight, double t, double angle) { + super(weight, angle); + this.t = t; + } + + public double getTheoreticalValue() { + double xt = x(t); + double yt = y(t); + return Math.sqrt(xt * xt + yt * yt); + } + + public double getPartial(EstimatedParameter parameter) { + double xt = x(t); + double yt = y(t); + double r = Math.sqrt(xt * xt + yt * yt); + if (parameter == x0) { + return xt / r; + } else if (parameter == vx0) { + return xt * t / r; + } else if (parameter == y0) { + return yt / r; + } else { + return yt * t / r; + } + } + + private final double t; + private static final long serialVersionUID = 3257286197740459503L; + + } + + private double t0; + private EstimatedParameter x0; + private EstimatedParameter y0; + private EstimatedParameter vx0; + private EstimatedParameter vy0; + +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/analysis.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,519 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Numerical Analysis</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <strong>Numerical Analysis</strong> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a4_Numerical_Analysis"></a>4 Numerical Analysis</h2> +<div class="section"><h3><a name="a4.1_Overview"></a>4.1 Overview</h3> +<p> + The analysis package is the parent package for algorithms dealing with + real-valued functions of one real variable. It contains dedicated sub-packages + providing numerical root-finding, integration, and interpolation. It also + contains a polynomials sub-package that considers polynomials with real + coefficients as differentiable real functions. + </p> +<p> + Functions interfaces are intended to be implemented by user code to represent + their domain problems. The algorithms provided by the library will then operate + on these function to find their roots, or integrate them, or ... Functions can + be multivariate or univariate, real vectorial or matrix valued, and they can be + differentiable or not. + </p> +<p> + Possible future additions may include numerical differentiation. + </p> +</div> +<div class="section"><h3><a name="a4.2_Root-finding"></a>4.2 Root-finding</h3> +<p> + A <a href="../apidocs/org/apache/commons/math/analysis/solvers/UnivariateRealSolver.html"> + org.apache.commons.math.analysis.solvers.UnivariateRealSolver.</a> + provides the means to find roots of <a href="../apidocs/org/apache/commons/math/analysis/UnivariateRealFunction.html">univariate real-valued functions</a>. + A root is the value where the function takes the value 0. Commons-Math + includes implementations of the following root-finding algorithms: <ul><li><a href="../apidocs/org/apache/commons/math/analysis/solvers/BisectionSolver.html"> + Bisection</a></li> +<li><a href="../apidocs/org/apache/commons/math/analysis/solvers/BrentSolver.html"> + Brent-Dekker</a></li> +<li><a href="../apidocs/org/apache/commons/math/analysis/solvers/NewtonSolver.html"> + Newton's Method</a></li> +<li><a href="../apidocs/org/apache/commons/math/analysis/solvers/SecantSolver.html"> + Secant Method</a></li> +<li><a href="../apidocs/org/apache/commons/math/analysis/solvers/MullerSolver.html"> + Muller's Method</a></li> +<li><a href="../apidocs/org/apache/commons/math/analysis/solvers/LaguerreSolver.html"> + Laguerre's Method</a></li> +<li><a href="../apidocs/org/apache/commons/math/analysis/solvers/RidderSolver.html"> + Ridder's Method</a></li> +</ul> +</p> +<p> + There are numerous non-obvious traps and pitfalls in root finding. + First, the usual disclaimers due to the way real world computers + calculate values apply. If the computation of the function provides + numerical instabilities, for example due to bit cancellation, the root + finding algorithms may behave badly and fail to converge or even + return bogus values. There will not necessarily be an indication that + the computed root is way off the true value. Secondly, the root finding + problem itself may be inherently ill-conditioned. There is a + "domain of indeterminacy", the interval for which the function has + near zero absolute values around the true root, which may be large. + Even worse, small problems like roundoff error may cause the function + value to "numerically oscillate" between negative and positive values. + This may again result in roots way off the true value, without + indication. There is not much a generic algorithm can do if + ill-conditioned problems are met. A way around this is to transform + the problem in order to get a better conditioned function. Proper + selection of a root-finding algorithm and its configuration parameters + requires knowledge of the analytical properties of the function under + analysis and numerical analysis techniques. Users are encouraged + to consult a numerical analysis text (or a numerical analyst) when + selecting and configuring a solver. + </p> +<p> + In order to use the root-finding features, first a solver object must + be created. It is encouraged that all solver object creation occurs + via the <code>org.apache.commons.math.analysis.solvers.UnivariateRealSolverFactory</code> + class. <code>UnivariateRealSolverFactory</code> is a simple factory + used to create all of the solver objects supported by Commons-Math. + The typical usage of <code>UnivariateRealSolverFactory</code> + to create a solver object would be:</p> +<div class="source"><pre>UnivariateRealSolverFactory factory = UnivariateRealSolverFactory.newInstance(); +UnivariateRealSolver solver = factory.newDefaultSolver();</pre> +</div> +<p> + The solvers that can be instantiated via the + <code>UnivariateRealSolverFactory</code> are detailed below: + <table class="bodyTable"><tr class="a"><th>Solver</th> +<th>Factory Method</th> +<th>Notes on Use</th> +</tr> +<tr class="b"><td>Bisection</td> +<td>newBisectionSolver</td> +<td><div>Root must be bracketted.</div><div>Linear, guaranteed convergence</div></td> +</tr> +<tr class="a"><td>Brent</td> +<td>newBrentSolver</td> +<td><div>Root must be bracketted.</div><div>Super-linear, guaranteed convergence</div></td> +</tr> +<tr class="b"><td>Newton</td> +<td>newNewtonSolver</td> +<td><div>Uses single value for initialization.</div><div>Super-linear, non-guaranteed convergence</div><div>Function must be differentiable</div></td> +</tr> +<tr class="a"><td>Secant</td> +<td>newSecantSolver</td> +<td><div>Root must be bracketted.</div><div>Super-linear, non-guaranteed convergence</div></td> +</tr> +<tr class="b"><td>Muller</td> +<td>newMullerSolver</td> +<td><div>Root must be bracketted.</div><div>We restrict ourselves to real valued functions, not complex ones</div></td> +</tr> +<tr class="a"><td>Laguerre</td> +<td>newLaguerreSolver</td> +<td><div>Root must be bracketted.</div><div>Function must be a polynomial</div></td> +</tr> +<tr class="b"><td>Ridder</td> +<td>newRidderSolver</td> +<td><div>Root must be bracketted.</div><div></div></td> +</tr> +</table> +</p> +<p> + Using a solver object, roots of functions are easily found using the <code>solve</code> + methods. For a function <code>f</code>, and two domain values, <code>min</code> and + <code>max</code>, <code>solve</code> computes a value <code>c</code> such that: + <ul><li><code>f(c) = 0.0</code> (see "function value accuracy")</li> +<li><code>min <= c <= max</code></li> +</ul> +</p> +<p> + Typical usage: + </p> +<div class="source"><pre>UnivariateRealFunction function = // some user defined function object +UnivariateRealSolverFactory factory = UnivariateRealSolverFactory.newInstance(); +UnivariateRealSolver solver = factory.newBisectionSolver(); +double c = solver.solve(function, 1.0, 5.0);</pre> +</div> +<p> + The <code>BrentSolve</code> uses the Brent-Dekker algorithm which is + fast and robust. This algorithm is recommended for most users and the + <code>BrentSolver</code> is the default solver provided by the + <code>UnivariateRealSolverFactory</code>. If there are multiple roots + in the interval, or there is a large domain of indeterminacy, the + algorithm will converge to a random root in the interval without + indication that there are problems. Interestingly, the examined text + book implementations all disagree in details of the convergence + criteria. Also each implementation had problems for one of the test + cases, so the expressions had to be fudged further. Don't expect to + get exactly the same root values as for other implementations of this + algorithm. + </p> +<p> + The <code>SecantSolver</code> uses a variant of the well known secant + algorithm. It may be a bit faster than the Brent solver for a class + of well-behaved functions. + </p> +<p> + The <code>BisectionSolver</code> is included for completeness and for + establishing a fall back in cases of emergency. The algorithm is + simple, most likely bug free and guaranteed to converge even in very + adverse circumstances which might cause other algorithms to + malfunction. The drawback is of course that it is also guaranteed + to be slow. + </p> +<p> + The <code>UnivariateRealSolver</code> interface exposes many + properties to control the convergence of a solver. For the most part, + these properties should not have to change from their default values + to produce good results. In the circumstances where changing these + property values is needed, it is easily done through getter and setter + methods on <code>UnivariateRealSolver</code>: + <table class="bodyTable"><tr class="a"><th>Property</th> +<th>Methods</th> +<th>Purpose</th> +</tr> +<tr class="b"><td>Absolute accuracy</td> +<td><div>getAbsoluteAccuracy</div><div>resetAbsoluteAccuracy</div><div>setAbsoluteAccuracy</div></td> +<td> + The Absolute Accuracy is (estimated) maximal difference between + the computed root and the true root of the function. This is + what most people think of as "accuracy" intuitively. The default + value is chosen as a sane value for most real world problems, + for roots in the range from -100 to +100. For accurate + computation of roots near zero, in the range form -0.0001 to + +0.0001, the value may be decreased. For computing roots + much larger in absolute value than 100, the default absolute + accuracy may never be reached because the given relative + accuracy is reached first. + </td> +</tr> +<tr class="a"><td>Relative accuracy</td> +<td><div>getRelativeAccuracy</div><div>resetRelativeAccuracy</div><div>setRelativeAccuracy</div></td> +<td> + The Relative Accuracy is the maximal difference between the + computed root and the true root, divided by the maximum of the + absolute values of the numbers. This accuracy measurement is + better suited for numerical calculations with computers, due to + the way floating point numbers are represented. The default + value is chosen so that algorithms will get a result even for + roots with large absolute values, even while it may be + impossible to reach the given absolute accuracy. + </td> +</tr> +<tr class="b"><td>Function value accuracy</td> +<td><div>getFunctionValueAccuracy</div><div>resetFunctionValueAccuracy</div><div>setFunctionValueAccuracy</div></td> +<td> + This value is used by some algorithms in order to prevent + numerical instabilities. If the function is evaluated to an + absolute value smaller than the Function Value Accuracy, the + algorithms assume they hit a root and return the value + immediately. The default value is a "very small value". If the + goal is to get a near zero function value rather than an accurate + root, computation may be sped up by setting this value + appropriately. + </td> +</tr> +<tr class="a"><td>Maximum iteration count</td> +<td><div>getMaximumIterationCount</div><div>resetMaximumIterationCount</div><div>setMaximumIterationCount</div></td> +<td> + This is the maximal number of iterations the algorithm will try. + If this number is exceeded, non-convergence is assumed and a + <code>ConvergenceException</code> exception is thrown. The + default value is 100, which should be plenty, given that a + bisection algorithm can't get any more accurate after 52 + iterations because of the number of mantissa bits in a double + precision floating point number. If a number of ill-conditioned + problems is to be solved, this number can be decreased in order + to avoid wasting time. + </td> +</tr> +</table> +</p> +</div> +<div class="section"><h3><a name="a4.3_Interpolation"></a>4.3 Interpolation</h3> +<p> + A <a href="../apidocs/org/apache/commons/math/analysis/interpolation/UnivariateRealInterpolator.html"> + org.apache.commons.math.analysis.interpolation.UnivariateRealInterpolator</a> + is used to find a univariate real-valued function <code>f</code> which + for a given set of ordered pairs + (<code>x<sub>i</sub></code>,<code>y<sub>i</sub></code>) yields + <code>f(x<sub>i</sub>)=y<sub>i</sub></code> to the best accuracy possible. The result + is provided as an object implementing the <a href="../apidocs/org/apache/commons/math/analysis/UnivariateRealFunction.html"> + org.apache.commons.math.analysis.UnivariateRealFunction</a> interface. It can therefore + be evaluated at any point, including point not belonging to the original set. + Currently, only an interpolator for generating natural cubic splines and a polynomial + interpolator are available. There is no interpolator factory, mainly because the + interpolation algorithm is more determined by the kind of the interpolated function + rather than the set of points to interpolate. + There aren't currently any accuracy controls either, as interpolation + accuracy is in general determined by the algorithm. + </p> +<p>Typical usage:</p> +<div class="source"><pre>double x[] = { 0.0, 1.0, 2.0 }; +double y[] = { 1.0, -1.0, 2.0); +UnivariateRealInterpolator interpolator = new SplineInterpolator(); +UnivariateRealFunction function = interpolator.interpolate(x, y); +double interpolationX = 0.5; +double interpolatedY = function.evaluate(x); +System.out println("f(" + interpolationX + ") = " + interpolatedY);</pre> +</div> +<p> + A natural cubic spline is a function consisting of a polynomial of + third degree for each subinterval determined by the x-coordinates of the + interpolated points. A function interpolating <code>N</code> + value pairs consists of <code>N-1</code> polynomials. The function + is continuous, smooth and can be differentiated twice. The second + derivative is continuous but not smooth. The x values passed to the + interpolator must be ordered in ascending order. It is not valid to + evaluate the function for values outside the range + <code>x<sub>0</sub></code>..<code>x<sub>N</sub></code>. + </p> +<p> + The polynomial function returned by the Neville's algorithm is a single + polynomial guaranteed to pass exactly through the interpolation points. + The degree of the polynomial is the number of points minus 1 (i.e. the + interpolation polynomial for a three points set will be a quadratic + polynomial). Despite the fact the interpolating polynomials is a perfect + approximation of a function at interpolation points, it may be a loose + approximation between the points. Due to <a href="http://en.wikipedia.org/wiki/Runge's_phenomenon" class="externalLink">Runge's phenomenom</a> + the error can get worse as the degree of the polynomial increases, so + adding more points does not always lead to a better interpolation. + </p> +<p> + Loess (or Lowess) interpolation is a robust interpolation useful for + smoothing univariate scaterplots. It has been described by William + Cleveland in his 1979 seminal paper <a href="http://www.math.tau.ac.il/~yekutiel/MA%20seminar/Cleveland%201979.pdf" class="externalLink">Robust + Locally Weighted Regression and Smoothing Scatterplots</a>. This kind of + interpolation is computationally intensive but robust. + </p> +<p> + Microsphere interpolation is a robust multidimensional interpolation algorithm. + It has been described in William Dudziak's <a href="http://www.dudziak.com/microsphere.pdf" class="externalLink">MS thesis</a>. + </p> +<p> + A <a href="../apidocs/org/apache/commons/math/analysis/interpolation/BivariateRealGridInterpolator.html"> + org.apache.commons.math.analysis.interpolation.BivariateRealGridInterpolator</a> + is used to find a bivariate real-valued function <code>f</code> which + for a given set of tuples + (<code>x<sub>i</sub></code>,<code>y<sub>j</sub></code>,<code>z<sub>ij</sub></code>) + yields <code>f(x<sub>i</sub>,y<sub>j</sub>)=z<sub>ij</sub></code> to the best accuracy + possible. The result is provided as an object implementing the + <a href="../apidocs/org/apache/commons/math/analysis/BivariateRealFunction.html"> + org.apache.commons.math.analysis.BivariateRealFunction</a> interface. It can therefore + be evaluated at any point, including a point not belonging to the original set. + The array <code>x<sub>i</sub></code> and <code>y<sub>j</sub></code> must be sorted in + increasing order in order to define a two-dimensional regular grid. + </p> +<p> + In <a href="../apidocs/org/apache/commons/math/analysis/interpolation/BicubicSplineInterpolatingFunction.html"> + bicubic interpolation</a>, the interpolation function is a 3rd-degree polynomial of two + variables. The coefficients are computed from the function values sampled on a regular grid, + as well as the values of the partial derivatives of the function at those grid points. + </p> +<p> + From two-dimensional data sampled on a regular grid, the + <a href="../apidocs/org/apache/commons/math/analysis/interpolation/SmoothingBicubicSplineInterpolator.html"> + org.apache.commons.math.analysis.interpolation.SmoothingBicubicSplineInterpolator</a> + computes a <a href="../apidocs/org/apache/commons/math/analysis/interpolation/BicubicSplineInterpolatingFunction.html"> + bicubic interpolating function</a>. The data is first smoothed, along each grid dimension, + using one-dimensional splines. + </p> +</div> +<div class="section"><h3><a name="a4.4_Integration"></a>4.4 Integration</h3> +<p> + A <a href="../apidocs/org/apache/commons/math/analysis/integration/UnivariateRealIntegrator.html"> + org.apache.commons.math.analysis.integration.UnivariateRealIntegrator.</a> + provides the means to numerically integrate <a href="../apidocs/org/apache/commons/math/analysis/UnivariateRealFunction.html">univariate real-valued functions</a>. + Commons-Math includes implementations of the following integration algorithms: <ul><li><a href="../apidocs/org/apache/commons/math/analysis/integration/RombergIntegrator.html"> + Romberg's method</a></li> +<li><a href="../apidocs/org/apache/commons/math/analysis/integration/SimpsonIntegrator.html"> + Simpson's method</a></li> +<li><a href="../apidocs/org/apache/commons/math/analysis/integration/TrapezoidIntegrator.html"> + trapezoid method</a></li> +<li><a href="../apidocs/org/apache/commons/math/analysis/integration/LegendreGaussIntegrator.html"> + Legendre-Gauss method</a></li> +</ul> +</p> +</div> +<div class="section"><h3><a name="a4.5_Polynomials"></a>4.5 Polynomials</h3> +<p> + The <a href="../apidocs/org/apache/commons/math/analysis/polynomials/package-summary.html"> + org.apache.commons.math.analysis.polynomials</a> package provides real coefficients + polynomials. + </p> +<p> + The <a href="../apidocs/org/apache/commons/math/analysis/polynomials/PolynomialFunction.html"> + org.apache.commons.math.analysis.polynomials.PolynomialFunction</a> class is the most general + one, using traditional coefficients arrays. The <a href="../apidocs/org/apache/commons/math/analysis/polynomials/PolynomialsUtils.html"> + org.apache.commons.math.analysis.polynomials.PolynomialsUtils</a> utility class provides static + factory methods to build Chebyshev, Hermite, Lagrange and Legendre polynomials. Coefficients + are computed using exact fractions so these factory methods can build polynomials up to any degree. + </p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/complex.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,299 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Complex Numbers</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <strong>Complex Numbers</strong> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a7_Complex_Numbers"></a>7 Complex Numbers</h2> +<div class="section"><h3><a name="a7.1_Overview"></a>7.1 Overview</h3> +<p> + The complex packages provides a complex number type as well as complex + versions of common transcendental functions and complex number + formatting. + </p> +</div> +<div class="section"><h3><a name="a7.2_Complex_Numbers"></a>7.2 Complex Numbers</h3> +<p><a href="../apidocs/org/apache/commons/math/complex/Complex.html"> + org.apache.commons.math.complex.Complex</a> provides a complex number + type that forms the basis for the complex functionality found in + commons-math. + </p> +<p> + Complex functions and arithmetic operations are implemented in + commons-math by applying standard computational formulas and + following the rules for <code>java.lang.Double</code> arithmetic in + handling infinite and <code>NaN</code> values. No attempt is made + to comply with ANSII/IEC C99x Annex G or any other standard for + Complex arithmetic. See the class and method javadocs for the + <a href="../apidocs/org/apache/commons/math/complex/Complex.html"> + Complex</a> and + <a href="../apidocs/org/apache/commons/math/complex/ComplexUtils.html"> + ComplexUtils</a> classes for details on computing formulas. + </p> +<p> + To create a complex number, simply call the constructor passing in two + floating-point arguments, the first being the real part of the + complex number and the second being the imaginary part: + <div class="source"><pre>Complex c = new Complex(1.0, 3.0); // 1 + 3i</pre> +</div> +</p> +<p> + Complex numbers may also be created from polar representations + using the <code>polar2Complex</code> method in + <code>ComplexUtils</code>. + </p> +<p> + The <code>Complex</code> class provides basic unary and binary + complex number operations. These operations provide the means to add, + subtract, multiply and divide complex numbers along with other + complex number functions similar to the real number functions found in + <code>java.math.BigDecimal</code>: + <div class="source"><pre>Complex lhs = new Complex(1.0, 3.0); +Complex rhs = new Complex(2.0, 5.0); + +Complex answer = lhs.add(rhs); // add two complex numbers + answer = lhs.subtract(rhs); // subtract two complex numbers + answer = lhs.abs(); // absolute value + answer = lhs.conjugate(rhs); // complex conjugate</pre> +</div> +</p> +</div> +<div class="section"><h3><a name="a7.3_Complex_Transcendental_Functions"></a>7.3 Complex Transcendental Functions</h3> +<p><a href="../apidocs/org/apache/commons/math/complex/Complex.html"> + org.apache.commons.math.complex.Complex</a> also provides + implementations of serveral transcendental functions involving complex + number arguments. Prior to version 1.2, these functions were provided + by <a href="../apidocs/org/apache/commons/math/complex/ComplexUtils.html"> + org.apache.commons.math.complex.ComplexUtils</a> in a way similar to the real + number functions found in <code>java.lang.Math</code>, but this has been + deprecated. These operations provide the means to compute the log, sine, + tangent, and other complex values : + <div class="source"><pre>Complex first = new Complex(1.0, 3.0); +Complex second = new Complex(2.0, 5.0); + +Complex answer = first.log(); // natural logarithm. + answer = first.cos(); // cosine + answer = first.pow(second); // first raised to the power of second</pre> +</div> +</p> +</div> +<div class="section"><h3><a name="a7.4_Complex_Formatting_and_Parsing"></a>7.4 Complex Formatting and Parsing</h3> +<p><code>Complex</code> instances can be converted to and from strings + using the<a href="../apidocs/org/apache/commons/math/complex/ComplexFormat.html"> + org.apache.commons.math.complex.ComplexFormat</a> class. + <code>ComplexFormat</code> is a <code>java.text.Format</code> + extension and, as such, is used like other formatting objects (e.g. + <code>java.text.SimpleDateFormat</code>): + <div class="source"><pre>ComplexFormat format = new ComplexFormat(); // default format +Complex c = new Complex(1.1111, 2.2222); +String s = format.format(c); // s contains "1.11 + 2.22i"</pre> +</div> +</p> +<p> + To customize the formatting output, one or two + <code>java.text.NumberFormat</code> instances can be used to construct + a <code>ComplexFormat</code>. These number formats control the + formatting of the real and imaginary values of the complex number: + <div class="source"><pre>NumberFormat nf = NumberFormat.getInstance(); +nf.setMinimumFractionDigits(3); +nf.setMaximumFractionDigits(3); + +// create complex format with custom number format +// when one number format is used, both real and +// imaginary parts are formatted the same +ComplexFormat cf = new ComplexFormat(nf); +Complex c = new Complex(1.11, 2.2222); +String s = format.format(c); // s contains "1.110 + 2.222i" + +NumberFormat nf2 = NumberFormat.getInstance(); +nf.setMinimumFractionDigits(1); +nf.setMaximumFractionDigits(1); + +// create complex format with custom number formats +cf = new ComplexFormat(nf, nf2); +s = format.format(c); // s contains "1.110 + 2.2i"</pre> +</div> +</p> +<p> + Another formatting customization provided by + <code>ComplexFormat</code> is the text used for the imaginary + designation. By default, the imaginary notation is "i" but, it can be + manipulated using the <code>setImaginaryCharacter</code> method. + </p> +<p> + Formatting inverse operation, parsing, can also be performed by + <code>ComplexFormat</code>. Parse a complex number from a string, + simply call the <code>parse</code> method: + <div class="source"><pre>ComplexFormat cf = new ComplexFormat(); +Complex c = cf.parse("1.110 + 2.222i");</pre> +</div> +</p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/distribution.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,232 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Statistics</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <strong>Distributions</strong> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a8_Probability_Distributions"></a>8 Probability Distributions</h2> +<div class="section"><h3><a name="a8.1_Overview"></a>8.1 Overview</h3> +<p> + The distributions package provide a framework for some commonly used + probability distributions. + </p> +</div> +<div class="section"><h3><a name="a8.2_Distribution_Framework"></a>8.2 Distribution Framework</h3> +<p> + The distribution framework provides the means to compute probability density + function (PDF) probabilities and cumulative distribution function (CDF) + probabilities for common probability distributions. Along with the direct + computation of PDF and CDF probabilities, the framework also allows for the + computation of inverse PDF and inverse CDF values. + </p> +<p> + Using a distribution object, PDF and CDF probabilities are easily computed + using the <code>cumulativeProbability</code> methods. For a distribution <code>X</code>, + and a domain value, <code>x</code>, <code>cumulativeProbability</code> computes + <code>P(X <= x)</code> (i.e. the lower tail probability of <code>X</code>). + </p> +<div class="source"><pre>TDistribution t = new TDistributionImpl(29); +double lowerTail = t.cumulativeProbability(-2.656); // P(T <= -2.656) +double upperTail = 1.0 - t.cumulativeProbability(2.75); // P(T >= 2.75)</pre> +</div> +<p> + The inverse PDF and CDF values are just as easily computed using the + <code>inverseCumulativeProbability</code> methods. For a distribution <code>X</code>, + and a probability, <code>p</code>, <code>inverseCumulativeProbability</code> + computes the domain value <code>x</code>, such that: + <ul><li><code>P(X <= x) = p</code>, for continuous distributions</li> +<li><code>P(X <= x) <= p</code>, for discrete distributions</li> +</ul> + + Notice the different cases for continuous and discrete distributions. This is the result + of PDFs not being invertible functions. As such, for discrete distributions, an exact + domain value can not be returned. Only the "best" domain value. For Commons-Math, the "best" + domain value is determined by the largest domain value whose cumulative probability is + less-than or equal to the given probability. + </p> +</div> +<div class="section"><h3><a name="a8.3_User_Defined_Distributions"></a>8.3 User Defined Distributions</h3> +<p> + Since there are numerous distributions and Commons-Math only directly supports a handful, + it may be necessary to extend the distribution framework to satisfy individual needs. It + is recommended that the <code>Distribution</code>, <code>ContinuousDistribution</code>, + <code>DiscreteDistribution</code>, and <code>IntegerDistribution</code> interfaces serve as + base types for any extension. These serve as the basis for all the distributions directly + supported by Commons-Math and using those interfaces for implementation purposes will + insure any extension is compatible with the remainder of Commons-Math. To aid in + implementing a distribution extension, the <code>AbstractDistribution</code>, + <code>AbstractContinuousDistribution</code>, and <code>AbstractIntegerDistribution</code> + provide implementation building blocks and offer a lot of default distribution + functionality. By extending these abstract classes directly, a good portion of the + repetitive distribution implementation is already developed and should save time and effort + in developing user defined distributions. + </p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/fraction.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,260 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Fractions</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <strong>Fractions</strong> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a9_Fractions"></a>9 Fractions</h2> +<div class="section"><h3><a name="a9.1_Overview"></a>9.1 Overview</h3> +<p> + The fraction packages provides a fraction number type as well as + fraction number formatting. + </p> +</div> +<div class="section"><h3><a name="a9.2_Fraction_Numbers"></a>9.2 Fraction Numbers</h3> +<p><a href="../apidocs/org/apache/commons/math/fraction/Fraction.html"> + org.apache.commons.math.fraction.Fraction</a> and + <a href="../apidocs/org/apache/commons/math/fraction/BigFraction.html"> + org.apache.commons.math.fraction.BigFraction</a> provide fraction number + type that forms the basis for the fraction functionality found in + commons-math. The former one can be used for fractions whose numerators + and denominators are small enough to fit in an int (taking care of intermediate + values) while the second class should be used when there is a risk the numerator + and denominator grow very large. + </p> +<p> + A fraction number, can be built from two integer arguments representing numerator + and denominator or from a double which will be approximated: + <div class="source"><pre>Fraction f = new Fraction(1, 3); // 1 / 3 +Fraction g = new Fraction(0.25); // 1 / 4</pre> +</div> +</p> +<p> + Of special note with fraction construction, when a fraction is created it is always reduced to lowest terms. + </p> +<p> + The <code>Fraction</code> class provides many unary and binary + fraction operations. These operations provide the means to add, + subtract, multiple and, divide fractions along with other functions similar to the real number functions found in + <code>java.math.BigDecimal</code>: + <div class="source"><pre>Fraction lhs = new Fraction(1, 3); +Fraction rhs = new Fraction(2, 5); + +Fraction answer = lhs.add(rhs); // add two fractions + answer = lhs.subtract(rhs); // subtract two fractions + answer = lhs.abs(); // absolute value + answer = lhs.reciprocal(); // reciprocal of lhs</pre> +</div> +</p> +<p> + Like fraction construction, for each of the fraction functions, the resulting fraction is reduced to lowest terms. + </p> +</div> +<div class="section"><h3><a name="a9.3_Fraction_Formatting_and_Parsing"></a>9.3 Fraction Formatting and Parsing</h3> +<p><code>Fraction</code> instances can be converted to and from strings + using the<a href="../apidocs/org/apache/commons/math/fraction/FractionFormat.html"> + org.apache.commons.math.fraction.FractionFormat</a> class. + <code>FractionFormat</code> is a <code>java.text.Format</code> + extension and, as such, is used like other formatting objects (e.g. + <code>java.text.SimpleDateFormat</code>): + <div class="source"><pre>FractionFormat format = new FractionFormat(); // default format +Fraction f = new Fraction(2, 4); +String s = format.format(f); // s contains "1 / 2", note the reduced fraction</pre> +</div> +</p> +<p> + To customize the formatting output, one or two + <code>java.text.NumberFormat</code> instances can be used to construct + a <code>FractionFormat</code>. These number formats control the + formatting of the numerator and denominator of the fraction: + <div class="source"><pre>NumberFormat nf = NumberFormat.getInstance(Locale.FRANCE); +// create fraction format with custom number format +// when one number format is used, both numerator and +// denominator are formatted the same +FractionFormat format = new FractionFormat(nf); +Fraction f = new Fraction(2000, 3333); +String s = format.format(c); // s contains "2.000 / 3.333" + +NumberFormat nf2 = NumberFormat.getInstance(Locale.US); +// create fraction format with custom number formats +format = new FractionFormat(nf, nf2); +s = format.format(f); // s contains "2.000 / 3,333"</pre> +</div> +</p> +<p> + Formatting's inverse operation, parsing, can also be performed by + <code>FractionFormat</code>. To parse a fraction from a string, + simply call the <code>parse</code> method: + <div class="source"><pre>FractionFormat ff = new FractionFormat(); +Fraction f = ff.parse("-10 / 21");</pre> +</div> +</p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/genetics.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,292 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Genetic Algorithms</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <strong>Genetic Algorithms</strong> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a14_Genetic_Algorithms"></a>14 Genetic Algorithms</h2> +<div class="section"><h3><a name="a14.1_Overview"></a>14.1 Overview</h3> +<p> + The genetics package provides a framework and implementations for + genetic algorithms. + </p> +</div> +<div class="section"><h3><a name="a14.2_GA_Framework"></a>14.2 GA Framework</h3> +<p><a href="../apidocs/org/apache/commons/math/genetics/GeneticAlgorithm.html"> + org.apache.commons.math.genetic.GeneticAlgorithm</a> provides an + execution framework for Genetic Algorithms (GA). + <a href="../apidocs/org/apache/commons/math/genetics/Population.html">Populations,</a> consisting + of <a href="../apidocs/org/apache/commons/math/genetics/Chromosome.html"> + Chromosomes</a> are evolved by the <code>GeneticAlgorithm</code> until a + <a href="../apidocs/org/apache/commons/math/genetics/StoppingCondition.html">StoppingCondition</a> + is reached. Evolution is determined by + <a href="../apidocs/org/apache/commons/math/genetics/SelectionPolicy.html">SelectionPolicies</a>, + <a href="../apidocs/org/apache/commons/math/genetics/MutationPolicy.html"> MutationPolicies</a> + and <a href="../apidocs/org/apache/commons/math/genetics/Fitness.html">Fitness</a>. + </p> +<p> + The GA itself is implemented by the <code>evolve</code> method of the <code>GeneticAlgorithm</code> class, + which looks like this: + <div class="source"><pre> +public Population evolve(Population initial, StoppingCondition condition) { + Population current = initial; + while (!condition.isSatisfied(current)) { + current = nextGeneration(current); + } + return current; +} + </pre> +</div> + + The <code>nextGeneration</code> method implements the following algorithm: + <ol type="1"><li>Get nextGeneration population to fill from <code>current</code> + generation, using its nextGeneration method</li> +<li>Loop until new generation is filled:</li> +<ul><li>Apply configured <code>SelectionPolicy</code> to select a pair of parents + from <code>current</code></li> +<li>With probability = + <a href="../apidocs/org/apache/commons/math/genetics/GeneticAlgorithm.html#getCrossoverRate()"> + getCrossoverRate()</a>, apply configured <code>CrossoverPolicy</code> to parents</li> +<li>With probability = + <a href="../apidocs/org/apache/commons/math/genetics/GeneticAlgorithm.html#getMutationRate()"> + getMutationRate()</a>, + apply configured <code>MutationPolicy</code> to each of the offspring</li> +<li>Add offspring individually to nextGeneration, + space permitting</li> +</ul> +<li>Return nextGeneration</li> +</ol> +</p> +</div> +<div class="section"><h3><a name="a14.3_Implementation"></a>14.3 Implementation</h3> +<p> + Here is an example GA execution: + <div class="source"><pre> +// initialize a new genetic algorithm +GeneticAlgorithm ga = new GeneticAlgorithm( + new OnePointCrossover<Integer>(), + 1, + new RandomKeyMutation(), + 0.10, + new TournamentSelection(TOURNAMENT_ARITY) +); + +// initial population +Population initial = getInitialPopulation(); + +// stopping condition +StoppingCondition stopCond = new FixedGenerationCount(NUM_GENERATIONS); + +// run the algorithm +Population finalPopulation = ga.evolve(initial, stopCond); + +// best chromosome from the final population +Chromosome bestFinal = finalPopulation.getFittestChromosome(); + </pre> +</div> + + The arguments to the <code>GeneticAlgorithm</code> constructor above are: <br /> +<table class="bodyTable"><tr class="a"><th>Parameter</th> +<th>value in example</th> +<th>meaning</th> +</tr> +<tr class="b"><td>crossoverPolicy</td> +<td><a href="../apidocs/org/apache/commons/math/genetics/OnePointCrossover.html">OnePointCrossover</a></td> +<td>A random crossover point is selected and the first part from each parent is copied to the corresponding + child, and the second parts are copied crosswise.</td> +</tr> +<tr class="a"><td>crossoverRate</td> +<td>1</td> +<td>Always apply crossover</td> +</tr> +<tr class="b"><td>mutationPolicy</td> +<td><a href="../apidocs/org/apache/commons/math/genetics/RandomKeyMutation.html">RandomKeyMutation</a></td> +<td>Changes a randomly chosen element of the array representation to a random value uniformly distributed in [0,1].</td> +</tr> +<tr class="a"><td>mutationRate</td> +<td>.1</td> +<td>Apply mutation with probability 0.1 - that is, 10% of the time.</td> +</tr> +<tr class="b"><td>selectionPolicy</td> +<td><a href="../apidocs/org/apache/commons/math/genetics/TournamentSelection.html">TournamentSelection</a></td> +<td>Each of the two selected chromosomes is selected based on an n-ary tournament -- this is done by drawing + n random chromosomes without replacement from the population, and then selecting the fittest chromosome among them.</td> +</tr> +</table> +<br /> + + The algorithm starts with an <code>initial</code> population of <code>Chromosomes.</code> and executes until + the specified <a href="../apidocs/org/apache/commons/math/genetics/StoppingCondition.html">StoppingCondition</a> + is reached. In the example above, a + <a href="../apidocs/org/apache/commons/math/genetics/FixedGenerationCount.html">FixedGenerationCount</a> + stopping condition is used, which means the algorithm proceeds through a fixed number of generations. + </p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/geometry.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,282 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Geometry</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <strong>3D Geometry</strong> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a11_Geometry"></a>11 Geometry</h2> +<div class="section"><h3><a name="a11.1_Overview"></a>11.1 Overview</h3> +<p> + The geometry package provides classes useful for many physical simulations + in the real 3D space, namely vectors and rotations. + </p> +</div> +<div class="section"><h3><a name="a11.2_Vectors"></a>11.2 Vectors</h3> +<p><a href="../apidocs/org/apache/commons/math/geometry/Vector3D.html"> + org.apache.commons.math.geometry.Vector3D</a> provides a simple vector + type. One important feature is that instances of this class are guaranteed + to be immutable, this greatly simplifies modelling dynamical systems + with changing states: once a vector has been computed, a reference to it + is known to preserve its state as long as the reference itself is preserved. + </p> +<p> + Numerous constructors are available to create vectors. In addition to the + straightforward cartesian coordinates constructor, a constructor using + azimuthal coordinates can build normalized vectors and linear constructors + from one, two, three or four base vectors are also available. Constants have + been defined for the most commons vectors (plus and minus canonical axes, + null vector, and special vectors with infinite or NaN coordinates). + </p> +<p> + The generic vectorial space operations are available including dot product, + normalization, orthogonal vector finding and angular separation computation + which have a specific meaning in 3D. The 3D geometry specific cross product + is of course also implemented. + </p> +<p><a href="../apidocs/org/apache/commons/math/geometry/Vector3DFormat.html"> + org.apache.commons.math.geometry.Vector3DFormat</a> is a specialized format + for formatting output or parsing input with text representation of 3D vectors. + </p> +</div> +<div class="section"><h3><a name="a11.3_Rotations"></a>11.3 Rotations</h3> +<p><a href="../apidocs/org/apache/commons/math/geometry/Rotation.html"> + org.apache.commons.math.geometry.Rotation</a> represents 3D rotations. + Rotation instances are also immutable objects, as Vector3D instances. + </p> +<p> + Rotations can be represented by several different mathematical + entities (matrices, axe and angle, Cardan or Euler angles, + quaternions). This class presents a higher level abstraction, more + user-oriented and hiding implementation details. Well, for the + curious, we use quaternions for the internal representation. The user + can build a rotation from any of these representations, and any of + these representations can be retrieved from a <code>Rotation</code> + instance (see the various constructors and getters). In addition, a + rotation can also be built implicitely from a set of vectors and their + image. + </p> +<p> + This implies that this class can be used to convert from one + representation to another one. For example, converting a rotation + matrix into a set of Cardan angles can be done using the + following single line of code: + </p> +<div class="source"><pre>double[] angles = new Rotation(matrix, 1.0e-10).getAngles(RotationOrder.XYZ);</pre> +</div> +<p> + Focus is oriented on what a rotation <em>does</em> rather than on its + underlying representation. Once it has been built, and regardless of + its internal representation, a rotation is an <em>operator</em> which + basically transforms three dimensional vectors into other three + dimensional vectors. Depending on the application, the meaning of + these vectors may vary as well as the semantics of the rotation. + </p> +<p> + For example in a spacecraft attitude simulation tool, users will + often consider the vectors are fixed (say the Earth direction for + example) and the rotation transforms the coordinates coordinates of + this vector in inertial frame into the coordinates of the same vector + in satellite frame. In this case, the rotation implicitly defines the + relation between the two frames (we have fixed vectors and moving frame). + Another example could be a telescope control application, where the + rotation would transform the sighting direction at rest into the desired + observing direction when the telescope is pointed towards an object of + interest. In this case the rotation transforms the direction at rest in + a topocentric frame into the sighting direction in the same topocentric + frame (we have moving vectors in fixed frame). In many case, both + approaches will be combined, in our telescope example, we will probably + also need to transform the observing direction in the topocentric frame + into the observing direction in inertial frame taking into account the + observatory location and the Earth rotation. + </p> +<p> + These examples show that a rotation means what the user wants it to + mean, so this class does not push the user towards one specific + definition and hence does not provide methods like + <code>projectVectorIntoDestinationFrame</code> or + <code>computeTransformedDirection</code>. It provides simpler and more + generic methods: <code>applyTo(Vector3D)</code> and + <code>applyInverseTo(Vector3D)</code>. + </p> +<p> + Since a rotation is basically a vectorial operator, several + rotations can be composed together and the composite operation + <code>r = r<sub>1</sub> o r<sub>2</sub></code> (which means that for each + vector <code>u</code>, <code>r(u) = r<sub>1</sub>(r<sub>2</sub>(u))</code>) + is also a rotation. Hence we can consider that in addition to vectors, a + rotation can be applied to other rotations as well (or to itself). With our + previous notations, we would say we can apply <code>r<sub>1</sub></code> to + <code>r<sub>2</sub></code> and the result we get is <code>r = + r<sub>1</sub> o r<sub>2</sub></code>. For this purpose, the class + provides the methods: <code>applyTo(Rotation)</code> and + <code>applyInverseTo(Rotation)</code>. + </p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/index.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,272 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Table of Contents</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <strong>Contents</strong> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="Table_of_Contents"></a>Table of Contents</h2> +<ul><li><a href="overview.html">0. Overview</a><ul><li><a href="overview.html#a0.1_About_the_User_Guide">0.1 About the User Guide</a></li> +<li><a href="overview.html#a0.2_Whats_in_commons-math">0.2 What's in commons-math</a></li> +<li><a href="overview.html#a0.3_How_commons-math_is_organized">0.3 How commons-math is organized</a></li> +<li><a href="overview.html#a0.4_How_interface_contracts_are_specified_in_commons-math_javadoc">0.4 How interface contracts are specified in commons-math javadoc</a></li> +<li><a href="overview.html#a0.5_Dependencies">0.5 Dependencies</a></li> +</ul> +</li> +<li><a href="stat.html">1. Statistics</a><ul><li><a href="stat.html#a1.1_Overview">1.1 Overview</a></li> +<li><a href="stat.html#a1.2_Descriptive_statistics">1.2 Descriptive statistics</a></li> +<li><a href="stat.html#a1.3_Frequency_distributions">1.3 Frequency distributions</a></li> +<li><a href="stat.html#a1.4_Simple_regression">1.4 Simple regression</a></li> +<li><a href="stat.html#a1.5_Multiple_linear_regression">1.5 Multiple Regression</a></li> +<li><a href="stat.html#a1.6_Rank_transformations">1.6 Rank transformations</a></li> +<li><a href="stat.html#a1.7_Covariance_and_correlation">1.7 Covariance and correlation</a></li> +<li><a href="stat.html#a1.8_Statistical_tests">1.8 Statistical Tests</a></li> +</ul> +</li> +<li><a href="random.html">2. Data Generation</a><ul><li><a href="random.html#a2.1_Overview">2.1 Overview</a></li> +<li><a href="random.html#a2.2_Random_numbers">2.2 Random numbers</a></li> +<li><a href="random.html#a2.3_Random_Vectors">2.3 Random Vectors</a></li> +<li><a href="random.html#a2.4_Random_Strings">2.4 Random Strings</a></li> +<li><a href="random.html#a2.5_Random_permutations_combinations_sampling">2.5 Random permutations, combinations, sampling</a></li> +<li><a href="random.html#a2.6_Generating_data_like_an_input_file">2.6 Generating data 'like' an input file</a></li> +<li><a href="random.html#a2.7_PRNG_Pluggability">2.7 PRNG Pluggability</a></li> +</ul> +</li> +<li><a href="linear.html">3. Linear Algebra</a><ul><li><a href="linear.html#a3.1_Overview">3.1 Overview</a></li> +<li><a href="linear.html#a3.2_Real_matrices">3.2 Real matrices</a></li> +<li><a href="linear.html#a3.3_Real_vectors">3.3 Real vectors</a></li> +<li><a href="linear.html#a3.4_Solving_linear_systems">3.4 Solving linear systems</a></li> +<li><a href="linear.html#a3.5_Eigenvalueseigenvectors_and_singular_valuessingular_vectors">3.5 Eigenvalues/eigenvectors and singular values/singular vectors</a></li> +<li><a href="linear.html#a3.6_Non-real_fields_complex_fractions_...">3.6 Non-real fields (complex, fractions ...)</a></li> +</ul> +</li> +<li><a href="analysis.html">4. Numerical Analysis</a><ul><li><a href="analysis.html#a4.1_Overview">4.1 Overview</a></li> +<li><a href="analysis.html#a4.2_Root-finding">4.2 Root-finding</a></li> +<li><a href="analysis.html#a4.3_Interpolation">4.3 Interpolation</a></li> +<li><a href="analysis.html#a4.4_Integration">4.4 Integration</a></li> +<li><a href="analysis.html#a4.5_Polynomials">4.5 Polynomials</a></li> +</ul> +</li> +<li><a href="special.html">5. Special Functions</a><ul><li><a href="special.html#a5.1_Overview">5.1 Overview</a></li> +<li><a href="special.html#a5.2_Erf_functions">5.2 Erf functions</a></li> +<li><a href="special.html#a5.3_Gamma_functions">5.3 Gamma functions</a></li> +<li><a href="special.html#a5.4_Beta_funtions">5.4 Beta funtions</a></li> +</ul> +</li> +<li><a href="utilities.html">6. Utilities</a><ul><li><a href="utilities.html#a6.1_Overview">6.1 Overview</a></li> +<li><a href="utilities.html#a6.2_Double_array_utilities">6.2 Double array utilities</a></li> +<li><a href="utilities.html#a6.3_intdouble_hash_map">6.3 int/double hash map</a></li> +<li><a href="utilities.html#a6.4_Continued_Fractions">6.4 Continued Fractions</a></li> +<li><a href="utilities.html#a6.5_binomial_coefficients_factorials_and_other_common_math_functions">6.5 binomial coefficients, factorials and other common math functions</a></li> +</ul> +</li> +<li><a href="complex.html">7. Complex Numbers</a><ul><li><a href="complex.html#a7.1_Overview">7.1 Overview</a></li> +<li><a href="complex.html#a7.2_Complex_Numbers">7.2 Complex Numbers</a></li> +<li><a href="complex.html#a7.3_Complex_Transcendental_Functions">7.3 Complex Transcendental Functions</a></li> +<li><a href="complex.html#a7.4_Complex_Formatting_and_Parsing">7.4 Complex Formatting and Parsing</a></li> +</ul> +</li> +<li><a href="distribution.html">8. Probability Distributions</a><ul><li><a href="distribution.html#a8.1_Overview">8.1 Overview</a></li> +<li><a href="distribution.html#a8.2_Distribution_Framework">8.2 Distribution Framework</a></li> +<li><a href="distribution.html#a8.3_User_Defined_Distributions">8.3 User Defined Distributions</a></li> +</ul> +</li> +<li><a href="fraction.html">9. Fractions</a><ul><li><a href="fraction.html#a9.1_Overview">9.1 Overview</a></li> +<li><a href="fraction.html#a9.2_Fraction_Numbers">9.2 Fraction Numbers</a></li> +<li><a href="fraction.html#a9.3_Fraction_Formatting_and_Parsing">9.3 Fraction Formatting and Parsing</a></li> +</ul> +</li> +<li><a href="transform.html">10. Transform methods</a></li> +<li><a href="geometry.html">11. Geometry</a><ul><li><a href="geometry.html#a11.1_Overview">11.1 Overview</a></li> +<li><a href="geometry.html#a11.2_Vectors">11.2 Vectors</a></li> +<li><a href="geometry.html#a11.3_Rotations">11.3 Rotations</a></li> +</ul> +</li> +<li><a href="optimization.html">12. Optimization</a><ul><li><a href="optimization.html#a12.1_Overview">12.1 Overview</a></li> +<li><a href="analysis.html#a12.2_Univariate_Functions">12.2 Univariate Functions</a></li> +<li><a href="analysis.html#a12.3_Linear_Programming">12.3 Linear Programming</a></li> +<li><a href="optimization.html#a12.4_Direct_Methods">12.4 Direct Methods</a></li> +<li><a href="analysis.html#a12.5_General_Case">12.5 General Case</a></li> +<li><a href="analysis.html#a12.6_Curve_Fitting">12.6 Curve Fitting</a></li> +</ul> +</li> +<li><a href="ode.html">13. Ordinary Differential Equations Integration</a><ul><li><a href="ode.html#a13.1_Overview">13.1 Overview</a></li> +<li><a href="ode.html#a13.2_Continuous_Output">13.2 Continuous Output</a></li> +<li><a href="ode.html#a13.3_Discrete_Events_Handling">13.3 Discrete Events Handling</a></li> +<li><a href="ode.html#a13.4_Available_Integrators">13.4 Available Integrators</a></li> +<li><a href="ode.html#a13.5_Derivatives">13.5 Derivatives</a></li> +</ul> +</li> +<li><a href="genetics.html">14. Genetic Algorithms</a><ul><li><a href="genetics.html#a14.1_Overview">14.1 Overview</a></li> +<li><a href="genetics.html#a14.2_GA_Framework">14.2 GA Framework</a></li> +<li><a href="genetics.html#a14.3_Implementation">14.3 Implementation and Examples</a></li> +</ul> +</li> +</ul> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/linear.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,362 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Linear Algebra</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <strong>Linear Algebra</strong> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a3_Linear_Algebra"></a>3 Linear Algebra</h2> +<div class="section"><h3><a name="a3.1_Overview"></a>3.1 Overview</h3> +<p> + Linear algebra support in commons-math provides operations on real matrices + (both dense and sparse matrices are supported) and vectors. It features basic + operations (addition, subtraction ...) and decomposition algorithms that can + be used to solve linear systems either in exact sense and in least squares sense. + </p> +</div> +<div class="section"><h3><a name="a3.2_Real_matrices"></a>3.2 Real matrices</h3> +<p> + The <a href="../apidocs/org/apache/commons/math/linear/RealMatrix.html"> + RealMatrix</a> interface represents a matrix with real numbers as + entries. The following basic matrix operations are supported: + <ul><li>Matrix addition, subtraction, multiplication</li> +<li>Scalar addition and multiplication</li> +<li>transpose</li> +<li>Norm and Trace</li> +<li>Operation on a vector</li> +</ul> +</p> +<p> + Example: + <div class="source"><pre> +// Create a real matrix with two rows and three columns +double[][] matrixData = { {1d,2d,3d}, {2d,5d,3d}}; +RealMatrix m = new Array2DRowRealMatrix(matrixData); + +// One more with three rows, two columns +double[][] matrixData2 = { {1d,2d}, {2d,5d}, {1d, 7d}}; +RealMatrix n = new Array2DRowRealMatrix(matrixData2); + +// Note: The constructor copies the input double[][] array. + +// Now multiply m by n +RealMatrix p = m.multiply(n); +System.out.println(p.getRowDimension()); // 2 +System.out.println(p.getColumnDimension()); // 2 + +// Invert p, using LU decomposition +RealMatrix pInverse = new LUDecompositionImpl(p).getSolver().getInverse(); + </pre> +</div> +</p> +<p> + The three main implementations of the interface are <a href="../apidocs/org/apache/commons/math/linear/Array2DRowRealMatrix.html"> + Array2DRowRealMatrix</a> and <a href="../apidocs/org/apache/commons/math/linear/BlockRealMatrix.html"> + BlockRealMatrix</a> for dense matrices (the second one being more suited to + dimensions above 50 or 100) and <a href="../apidocs/org/apache/commons/math/linear/SparseRealMatrix.html"> + SparseRealMatrix</a> for sparse matrices. + </p> +</div> +<div class="section"><h3><a name="a3.3_Real_vectors"></a>3.3 Real vectors</h3> +<p> + The <a href="../apidocs/org/apache/commons/math/linear/RealVector.html"> + RealVector</a> interface represents a vector with real numbers as + entries. The following basic matrix operations are supported: + <ul><li>Vector addition, subtraction</li> +<li>Element by element multiplication, division</li> +<li>Scalar addition, subtraction, multiplication, division and power</li> +<li>Mapping of mathematical functions (cos, sin ...)</li> +<li>Dot product, outer product</li> +<li>Distance and norm according to norms L1, L2 and Linf</li> +</ul> +</p> +<p> + The <a href="../apidocs/org/apache/commons/math/linear/RealVectorFormat.html"> + RealVectorFormat</a> class handles input/output of vectors in a customizable + textual format. + </p> +</div> +<div class="section"><h3><a name="a3.4_Solving_linear_systems"></a>3.4 Solving linear systems</h3> +<p> + The <code>solve()</code> methods of the <a href="../apidocs/org/apache/commons/math/linear/DecompositionSolver.html">DecompositionSolver</a> + interface support solving linear systems of equations of the form AX=B, either + in linear sense or in least square sense. A <code>RealMatrix</code> instance is + used to represent the coefficient matrix of the system. Solving the system is a + two phases process: first the coefficient matrix is decomposed in some way and + then a solver built from the decomposition solves the system. This allows to + compute the decomposition and build the solver only once if several systems have + to be solved with the same coefficient matrix. + </p> +<p> + For example, to solve the linear system + <pre> + 2x + 3y - 2z = 1 + -x + 7y + 6x = -2 + 4x - 3y - 5z = 1 + </pre> + Start by decomposing the coefficient matrix A (in this case using LU decomposition) + and build a solver + <div class="source"><pre> +RealMatrix coefficients = + new Array2DRowRealMatrix(new double[][] { { 2, 3, -2 }, { -1, 7, 6 }, { 4, -3, -5 } }, + false); +DecompositionSolver solver = new LUDecompositionImpl(coefficients).getSolver(); + </pre> +</div> + + Next create a <code>RealVector</code> array to represent the constant + vector B and use <code>solve(RealVector)</code> to solve the system + <div class="source"><pre> +RealVector constants = new RealVectorImpl(new double[] { 1, -2, 1 }, false); +RealVector solution = solver.solve(constants); + </pre> +</div> + + The <code>solution</code> vector will contain values for x + (<code>solution.getEntry(0)</code>), y (<code>solution.getEntry(1)</code>), + and z (<code>solution.getEntry(2)</code>) that solve the system. + </p> +<p> + Each type of decomposition has its specific semantics and constraints on + the coefficient matrix as shown in the following table. For algorithms that + solve AX=B in least squares sense the value returned for X is such that the + residual AX-B has minimal norm. If an exact solution exist (i.e. if for some + X the residual AX-B is exactly 0), then this exact solution is also the solution + in least square sense. This implies that algorithms suited for least squares + problems can also be used to solve exact problems, but the reverse is not true. + </p> +<p><table class="bodyTable"><tr class="a"><td><font size="+2">Decomposition algorithms</font></td> +</tr> +<tr class="b"><font size="+1"><td>Name</td> +<td>coefficients matrix</td> +<td>problem type</td> +</font></tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/linear/LUDecomposition.html">LU</a></td> +<td>square</td> +<td>exact solution only</td> +</tr> +<tr class="b"><td><a href="../apidocs/org/apache/commons/math/linear/CholeskyDecomposition.html">Cholesky</a></td> +<td>symmetric positive definite</td> +<td>exact solution only</td> +</tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/linear/QRDecomposition.html">QR</a></td> +<td>any</td> +<td>least squares solution</td> +</tr> +<tr class="b"><td><a href="../apidocs/org/apache/commons/math/linear/EigenDecomposition.html">eigen decomposition</a></td> +<td>square</td> +<td>exact solution only</td> +</tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/linear/SingularValueDecomposition.html">SVD</a></td> +<td>any</td> +<td>least squares solution</td> +</tr> +</table> +</p> +<p> + It is possible to use a simple array of double instead of a <code>RealVector</code>. + In this case, the solution will be provided also as an array of double. + </p> +<p> + It is possible to solve multiple systems with the same coefficient matrix + in one method call. To do this, create a matrix whose column vectors correspond + to the constant vectors for the systems to be solved and use <code>solve(RealMatrix),</code> + which returns a matrix with column vectors representing the solutions. + </p> +</div> +<div class="section"><h3><a name="a3.5_Eigenvalueseigenvectors_and_singular_valuessingular_vectors"></a>3.5 Eigenvalues/eigenvectors and singular values/singular vectors</h3> +<p> + Decomposition algorithms may be used for themselves and not only for linear system solving. + This is of prime interest with eigen decomposition and singular value decomposition. + </p> +<p> + The <code>getEigenvalue()</code>, <code>getEigenvalues()</code>, <code>getEigenVector()</code>, + <code>getV()</code>, <code>getD()</code> and <code>getVT()</code> methods of the + <code>EigenDecomposition</code> interface support solving eigenproblems of the form + AX = lambda X where lambda is a real scalar. + </p> +<p>The <code>getSingularValues()</code>, <code>getU()</code>, <code>getS()</code> and + <code>getV()</code> methods of the <code>SingularValueDecomposition</code> interface + allow to solve singular values problems of the form AXi = lambda Yi where lambda is a + real scalar, and where the Xi and Yi vectors form orthogonal bases of their respective + vector spaces (which may have different dimensions). + </p> +</div> +<div class="section"><h3><a name="a3.6_Non-real_fields_complex_fractions_..."></a>3.6 Non-real fields (complex, fractions ...)</h3> +<p> + In addition to the real field, matrices and vectors using non-real <a href="../apidocs/org/apache/commons/math/FieldElement.html">field elements</a> can be used. + The fields already supported by the library are: + <ul><li><a href="../apidocs/org/apache/commons/math/complex/Complex.html">Complex</a></li> +<li><a href="../apidocs/org/apache/commons/math/fraction/Fraction.html">Fraction</a></li> +<li><a href="../apidocs/org/apache/commons/math/fraction/BigFraction.html">BigFraction</a></li> +<li><a href="../apidocs/org/apache/commons/math/util/BigReal.html">BigReal</a></li> +</ul> +</p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/ode.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,609 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Ordinary Differential Equations Integration</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <strong>Ordinary Differential Equations</strong> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a13_Ordinary_Differential_Equations_Integration"></a>13 Ordinary Differential Equations Integration</h2> +<div class="section"><h3><a name="a13.1_Overview"></a>13.1 Overview</h3> +<p> + The ode package provides classes to solve Ordinary Differential Equations problems. + </p> +<p> + This package solves Initial Value Problems of the form y'=f(t,y) with t<sub>0</sub> + and y(t<sub>0</sub>)=y<sub>0</sub> known. The provided integrators compute an estimate + of y(t) from t=t<sub>0</sub> to t=t<sub>1</sub>. + </p> +<p> + All integrators provide dense output. This means that besides computing the state vector + at discrete times, they also provide a cheap mean to get both the state and its derivative + between the time steps. They do so through classes extending the + <a href="../apidocs/org/apache/commons/math/ode/sampling/StepInterpolator.html">StepInterpolator</a> + abstract class, which are made available to the user at the end of each step. + </p> +<p> + All integrators handle multiple discrete events detection based on switching + functions. This means that the integrator can be driven by user specified discrete events + (occurring when the sign of user-supplied <i>switching function</i> changes). The steps are + shortened as needed to ensure the events occur at step boundaries (even if the integrator + is a fixed-step integrator). When the events are triggered, integration can + be stopped (this is called a G-stop facility), the state vector can be changed, or integration + can simply go on. The latter case is useful to handle discontinuities in the differential + equations gracefully and get accurate dense output even close to the discontinuity. + </p> +<p> + All integrators support setting a maximal number of evaluations of differential + equations function. If this number is exceeded, an exception will be thrown during + integration. This can be used to prevent infinite loops if for example error control or + discrete events create a really large number of extremely small steps. By default, the + maximal number of evaluation is set to <code>Integer.MAX_VALUE</code> (i.e. 2<sup>31</sup>-1 + or 2147483647). It is recommended to set this maximal number to a value suited to the ODE + problem, integration range, and step size or error control settings. + </p> +<p> + The user should describe his problem in his own classes which should implement the + <a href="../apidocs/org/apache/commons/math/ode/FirstOrderDifferentialEquations.html">FirstOrderDifferentialEquations</a> + interface. Then he should pass it to the integrator he prefers among all the classes that implement + the <a href="../apidocs/org/apache/commons/math/ode/FirstOrderIntegrator.html">FirstOrderIntegrator</a> + interface. The following example shows how to implement the simple two-dimensional problem: + <ul><li>y'<sub>0</sub>(t) = ? × (c<sub>1</sub> - y<sub>1</sub>(t))</li> +<li>y'<sub>1</sub>(t) = ? × (y<sub>0</sub>(t) - c<sub>0</sub>)</li> +</ul> + + with some initial state y(t<sub>0</sub>) = (y<sub>0</sub>(t<sub>0</sub>), y<sub>1</sub>(t<sub>0</sub>)). + In fact, the exact solution of this problem is that y(t) moves along a circle + centered at c = (c<sub>0</sub>, c<sub>1</sub>) with constant angular rate ?. + </p> +<div class="source"><pre> +private static class CircleODE implements FirstOrderDifferentialEquations { + + private double[] c; + private double omega; + + public CircleODE(double[] c, double omega) { + this.c = c; + this.omega = omega; + } + + public int getDimension() { + return 2; + } + + public void computeDerivatives(double t, double[] y, double[] yDot) { + yDot[0] = omega * (c[1] - y[1]); + yDot[1] = omega * (y[0] - c[0]); + } + +} + </pre> +</div> +<p> + Computing the state y(16.0) starting from y(0.0) = (0.0, 1.0) and integrating the ODE + is done as follows (using Dormand-Prince 8(5,3) integrator as an example): + </p> +<div class="source"><pre> +FirstOrderIntegrator dp853 = new DormandPrince853Integrator(1.0e-8, 100.0, 1.0e-10, 1.0e-10); +FirstOrderDifferentialEquations ode = new CircleODE(new double[] { 1.0, 1.0 }, 0.1); +double[] y = new double[] { 0.0, 1.0 }; // initial state +dp853.integrate(ode, 0.0, y, 16.0, y); // now y contains final state at time t=16.0 + </pre> +</div> +</div> +<div class="section"><h3><a name="a13.2_Continuous_Output"></a>13.2 Continuous Output</h3> +<p> + The solution of the integration problem is provided by two means. The first one is aimed towards + simple use: the state vector at the end of the integration process is copied in the y array of the + <code>FirstOrderIntegrator.integrate</code> method, as shown by previous example. The second one + should be used when more in-depth information is needed throughout the integration process. The user + can register an object implementing the + <a href="../apidocs/org/apache/commons/math/ode/sampling/StepHandler.html">StepHandler</a> interface or a + <a href="../apidocs/org/apache/commons/math/ode/sampling/StepNormalizer.html">StepNormalizer</a> object wrapping + a user-specified object implementing the + <a href="../apidocs/org/apache/commons/math/ode/sampling/FixedStepHandler.html">FixedStepHandler</a> interface + into the integrator before calling the <code>FirstOrderIntegrator.integrate</code> method. The user object + will be called appropriately during the integration process, allowing the user to process intermediate + results. The default step handler does nothing. Considering again the previous example, we want to print the + trajectory of the point to check it really is a circle arc. We simply add the following before the call + to integrator.integrate: + </p> +<div class="source"><pre> +StepHandler stepHandler = new StepHandler() { + public void reset() {} + + public boolean requiresDenseOutput() { return false; } + + public void handleStep(StepInterpolator interpolator, boolean isLast) throws DerivativeException { + double t = interpolator.getCurrentTime(); + double[] y = interpolator.getInterpolatedY(); + System.out.println(t + " " + y[0] + " " + y[1]); + } +}; +integrator.addStepHandler(stepHandler); + </pre> +</div> +<p><a href="../apidocs/org/apache/commons/math/ode/ContinuousOutputModel.html">ContinuousOutputModel</a> + is a special-purpose step handler that is able to store all steps and to provide transparent access to + any intermediate result once the integration is over. An important feature of this class is that it + implements the <code>Serializable</code> interface. This means that a complete continuous model of the + integrated function throughout the integration range can be serialized and reused later (if stored into + a persistent medium like a file system or a database) or elsewhere (if sent to another application). + Only the result of the integration is stored, there is no reference to the integrated problem by itself. + </p> +<p> + Other default implementations of the <a href="../apidocs/org/apache/commons/math/ode/sampling/StepHandler.html">StepHandler</a> + interface are available for general needs + (<a href="../apidocs/org/apache/commons/math/ode/sampling/DummyStepHandler.html">DummyStepHandler</a>, + <a href="../apidocs/org/apache/commons/math/ode/sampling/StepNormalizer.html">StepNormalizer</a>) and custom + implementations can be developed for specific needs. As an example, if an application is to be + completely driven by the integration process, then most of the application code will be run inside a + step handler specific to this application. + </p> +<p> + Some integrators (the simple ones) use fixed steps that are set at creation time. The more efficient + integrators use variable steps that are handled internally in order to control the integration error + with respect to a specified accuracy (these integrators extend the + <a href="../apidocs/org/apache/commons/math/ode/AdaptiveStepsizeIntegrator.html">AdaptiveStepsizeIntegrator</a> + abstract class). In this case, the step handler which is called after each successful step shows up + the variable stepsize. The <a href="../apidocs/org/apache/commons/math/ode/sampling/StepNormalizer.html">StepNormalizer</a> + class can be used to convert the variable stepsize into a fixed stepsize that can be handled by classes + implementing the <a href="../apidocs/org/apache/commons/math/ode/sampling/FixedStepHandler.html">FixedStepHandler</a> + interface. Adaptive stepsize integrators can automatically compute the initial stepsize by themselves, + however the user can specify it if he prefers to retain full control over the integration or if the + automatic guess is wrong. + </p> +</div> +<div class="section"><h3><a name="a13.3_Discrete_Events_Handling"></a>13.3 Discrete Events Handling</h3> +<p> + ODE problems are continuous ones. However, sometimes discrete events must be + taken into account. The most frequent case is the stop condition of the integrator + is not defined by the time t but by a target condition on state y (say y[0] = 1.0 + for example). + </p> +<p> + Discrete events detection is based on switching functions. The user provides + a simple <a href="../apidocs/org/apache/commons/math/ode/events/EventHandler.html">g(t, y)</a> + function depending on the current time and state. The integrator will monitor + the value of the function throughout integration range and will trigger the + event when its sign changes. The magnitude of the value is almost irrelevant, + it should however be continuous (but not necessarily smooth) for the sake of + root finding. The steps are shortened as needed to ensure the events occur + at step boundaries (even if the integrator is a fixed-step integrator). + </p> +<p> + When an event is triggered, the event time, current state and an indicator + whether the switching function was increasing or decreasing at event time + are provided to the user. Several different options are available to him: + </p> +<ul><li>integration can be stopped (this is called a G-stop facility),</li> +<li>the state vector or the derivatives can be changed,</li> +<li>or integration can simply go on.</li> +</ul> +<p> + The first case, G-stop, is the most common one. A typical use case is when an + ODE must be solved up to some target state is reached, with a known value of + the state but an unknown occurrence time. As an example, if we want to monitor + a chemical reaction up to some predefined concentration for the first substance, + we can use the following switching function setting: + </p> +<div class="source"><pre> +public double g(double t, double[] y) { + return y[0] - targetConcentration; +} + +public int eventOccurred(double t, double[] y, boolean increasing) { + return STOP; +} + </pre> +</div> +<p> + The second case, change state vector or derivatives is encountered when dealing + with discontinuous dynamical models. A typical case would be the motion of a + spacecraft when thrusters are fired for orbital maneuvers. The acceleration is + smooth as long as no maneuvers are performed, depending only on gravity, drag, + third body attraction, radiation pressure. Firing a thruster introduces a + discontinuity that must be handled appropriately by the integrator. In such a case, + we would use a switching function setting similar to this: + </p> +<div class="source"><pre> +public double g(double t, double[] y) { + return (t - tManeuverStart) * (t - tManeuverStop); +} + +public int eventOccurred(double t, double[] y, boolean increasing) { + return RESET_DERIVATIVES; +} + </pre> +</div> +<p> + The third case is useful mainly for monitoring purposes, a simple example is: + </p> +<div class="source"><pre> +public double g(double t, double[] y) { + return y[0] - y[1]; +} + +public int eventOccurred(double t, double[] y, boolean increasing) { + logger.log("y0(t) and y1(t) curves cross at t = " + t); + return CONTINUE; +} + </pre> +</div> +</div> +<div class="section"><h3><a name="a13.4_Available_Integrators"></a>13.4 Available Integrators</h3> +<p> + The tables below show the various integrators available for non-stiff problems. Note that the + implementations of Adams-Bashforth and Adams-Moulton are adaptive stepsize, not fixed stepsize + as is usual for these multi-step integrators. This is due to the fact the implementation relies + on the Nordsieck vector representation of the state. + </p> +<p><table class="bodyTable"><tr class="a"><td><font size="+2">Fixed Step Integrators</font></td> +</tr> +<tr class="b"><font size="+1"><td>Name</td> +<td>Order</td> +</font></tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/EulerIntegrator.html">Euler</a></td> +<td>1</td> +</tr> +<tr class="b"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/MidpointIntegrator.html">Midpoint</a></td> +<td>2</td> +</tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/ClassicalRungeKuttaIntegrator.html">Classical Runge-Kutta</a></td> +<td>4</td> +</tr> +<tr class="b"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/GillIntegrator.html">Gill</a></td> +<td>4</td> +</tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/ThreeEighthesIntegrator.html">3/8</a></td> +<td>4</td> +</tr> +</table> +</p> +<p><table class="bodyTable"><tr class="b"><td><font size="+2">Adaptive Stepsize Integrators</font></td> +</tr> +<tr class="a"><font size="+1"><td>Name</td> +<td>Integration Order</td> +<td>Error Estimation Order</td> +</font></tr> +<tr class="b"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/HighamHall54Integrator.html">Higham and Hall</a></td> +<td>5</td> +<td>4</td> +</tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/DormandPrince54Integrator.html">Dormand-Prince 5(4)</a></td> +<td>5</td> +<td>4</td> +</tr> +<tr class="b"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/DormandPrince853Integrator.html">Dormand-Prince 8(5,3)</a></td> +<td>8</td> +<td>5 and 3</td> +</tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/GraggBulirschStoerIntegrator.html">Gragg-Bulirsch-Stoer</a></td> +<td>variable (up to 18 by default)</td> +<td>variable</td> +</tr> +<tr class="b"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/AdamsBashforthIntegrator.html">Adams-Bashforth</a></td> +<td>variable</td> +<td>variable</td> +</tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/ode/nonstiff/AdamsMoultonIntegrator.html">Adams-Moulton</a></td> +<td>variable</td> +<td>variable</td> +</tr> +</table> +</p> +</div> +<div class="section"><h3><a name="a13.5_Derivatives"></a>13.5 Derivatives</h3> +<p> + If in addition to state y(t) the user needs to compute the sensitivity of the state to + the initial state or some parameter of the ODE, he will use the classes and interfaces + from the <a href="../apidocs/org/apache/commons/math/ode/jacobians/package-summary.html">org.apache.commons.ode.jacobians</a> + package instead of the top level ode package. These classes compute the jacobians + dy(t)/dy<sub>0</sub> and dy(t<sub>0</sub>)/dp where y<sub>0</sub> is the initial state + and p is some ODE parameter. + </p> +<p> + The classes and interfaces in this package mimic the behavior of the classes and + interfaces of the top level ode package, only adding parameters arrays for the jacobians. + The behavior of these classes is to create a compound state vector z containing both + the state y(t) and its derivatives dy(t)/dy<sub>0</sub> and dy(t<sub>0</sub>)/dp and + to set up an extended problem by adding the equations for the jacobians automatically. + These extended state and problems are then provided to a classical underlying integrator + chosen by user. + </p> +<p> + This behavior imply there will be a top level integrator knowing about state and jacobians + and a low level integrator knowing only about compound state (which may be big). If the user + wants to deal with the top level only, he will use the specialized step handler and event + handler classes registered at top level. He can also register classical step handlers and + event handlers, but in this case will see the big compound state. This state is guaranteed + to contain the original state in the first elements, followed by the jacobian with respect + to initial state (in row order), followed by the jacobian with respect to parameters (in + row order). If for example the original state dimension is 6 and there are 3 parameters, + the compound state will be a 60 elements array. The first 6 elements will be the original + state, the next 36 elements will be the jacobian with respect to initial state, and the + remaining 18 will be the jacobian with respect to parameters. Dealing with low level + step handlers and event handlers is cumbersome if one really needs the jacobians in these + methods, but it also prevents many data being copied back and forth between state and + jacobians on one side and compound state on the other side. + </p> +<p> + In order to compute dy(t)/dy<sub>0</sub> and dy(t<sub>0</sub>)/dp for any t, the algorithm + needs not only the ODE function f such that y'=f(t,y) but also its local jacobians + df(t, y, p)/dy and df(t, y, p)/dp. + </p> +<p> + If the function f is too complex, the user can simply rely on internal differentiation + using finite differences to compute these local jacobians. So rather than the <a href="../apidocs/org/apache/commons/math/ode/FirstOrderDifferentialEquations.html">FirstOrderDifferentialEquations</a> + interface he will implement the <a href="../apidocs/org/apache/commons/math/ode/jacobians/ParameterizedODE.html">ParameterizedODE</a> + interface. Considering again our example where only ? is considered a parameter, we get: + </p> +<div class="source"><pre> +public class BasicCircleODE implements ParameterizedODE { + + private double[] c; + private double omega; + + public BasicCircleODE(double[] c, double omega) { + this.c = c; + this.omega = omega; + } + + public int getDimension() { + return 2; + } + + public void computeDerivatives(double t, double[] y, double[] yDot) { + yDot[0] = omega * (c[1] - y[1]); + yDot[1] = omega * (y[0] - c[0]); + } + + public int getParametersDimension() { + // we are only interested in the omega parameter + return 1; + } + + public void setParameter(int i, double value) { + omega = value; + } + +} + </pre> +</div> +<p> + This ODE is provided to the specialized integrator with two arrays specifying the + step sizes to use for finite differences (one array for derivation with respect to + state y, one array for derivation with respect to parameters p): + </p> +<div class="source"><pre> +double[] hY = new double[] { 0.001, 0.001 }; +double[] hP = new double[] { 1.0e-6 }; +FirstOrderIntegratorWithJacobians integrator = new FirstOrderIntegratorWithJacobians(dp853, ode, hY, hP); +integrator.integrate(t0, y0, dy0dp, t, y, dydy0, dydp); + </pre> +</div> +<p> + If the function f is simple, the user can simply provide the local jacobians + by himself. So rather than the <a href="../apidocs/org/apache/commons/math/ode/FirstOrderDifferentialEquations.html">FirstOrderDifferentialEquations</a> + interface he will implement the <a href="../apidocs/org/apache/commons/math/ode/jacobians/ODEWithJacobians.html">ODEWithJacobians</a> + interface. Considering again our example where only ? is considered a parameter, we get: + </p> +<div class="source"><pre> +public class EnhancedCircleODE implements ODEWithJacobians { + + private double[] c; + private double omega; + + public EnhancedCircleODE(double[] c, double omega) { + this.c = c; + this.omega = omega; + } + + public int getDimension() { + return 2; + } + + public void computeDerivatives(double t, double[] y, double[] yDot) { + yDot[0] = omega * (c[1] - y[1]); + yDot[1] = omega * (y[0] - c[0]); + } + + public int getParametersDimension() { + // we are only interested in the omega parameter + return 1; + } + + public void computeJacobians(double t, double[] y, double[] yDot, double[][] dFdY, double[][] dFdP) { + + dFdY[0][0] = 0; + dFdY[0][1] = -omega; + dFdY[1][0] = omega; + dFdY[1][1] = 0; + + dFdP[0][0] = 0; + dFdP[0][1] = omega; + dFdP[0][2] = c[1] - y[1]; + dFdP[1][0] = -omega; + dFdP[1][1] = 0; + dFdP[1][2] = y[0] - c[0]; + + } + +} + </pre> +</div> +<p> + This ODE is provided to the specialized integrator as is: + </p> +<div class="source"><pre> +FirstOrderIntegratorWithJacobians integrator = new FirstOrderIntegratorWithJacobians(dp853, ode); +integrator.integrate(t0, y0, dy0dp, t, y, dydy0, dydp); + </pre> +</div> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/optimization.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,390 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Optimization</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <strong>Optimization</strong> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a12_Optimization"></a>12 Optimization</h2> +<div class="section"><h3><a name="a12.1_Overview"></a>12.1 Overview</h3> +<p> + The optimization package provides algorithms to optimize (i.e. either minimize + or maximize) some objective or cost function. The package is split in several + sub-packages dedicated to different kind of functions or algorithms. + <ul><li>the univariate package handles univariate scalar functions,</li> +<li>the linear package handles multivariate vector linear functions + with linear constraints,</li> +<li>the direct package handles multivariate scalar functions + using direct search methods (i.e. not using derivatives),</li> +<li>the general package handles multivariate scalar or vector functions + using derivatives.</li> +<li>the fitting package handles curve fitting by univariate real functions</li> +</ul> +</p> +<p> + The top level optimization package provides common interfaces for the optimization + algorithms provided in sub-packages. The main interfaces defines defines optimizers + and convergence checkers. The functions that are optimized by the algorithms provided + by this package and its sub-packages are a subset of the one defined in the + <code>analysis</code> package, namely the real and vector valued functions. These + functions are called objective function here. When the goal is to minimize, the + functions are often called cost function, this name is not used in this package. + </p> +<p> + The type of goal, i.e. minimization or maximization, is defined by the enumerated + <a href="../apidocs/org/apache/commons/math/optimization/GoalType.html"> + GoalType</a> which has only two values: <code>MAXIMIZE</code> and <code>MINIMIZE</code>. + </p> +<p> + Optimizers are the algorithms that will either minimize or maximize, the objective + function by changing its input variables set until an optimal set is found. There + are only four interfaces defining the common behavior of optimizers, one for each + supported type of objective function: + <ul><li><a href="../apidocs/org/apache/commons/math/optimization/UnivariateRealOptimizer.html"> + UnivariateRealOptimizer</a> for <a href="../apidocs/org/apache/commons/math/analysis/UnivariateRealFunction.html"> + univariate real functions</a></li> +<li><a href="../apidocs/org/apache/commons/math/optimization/MultivariateRealOptimizer.html"> + MultivariateRealOptimizer</a> for <a href="../apidocs/org/apache/commons/math/analysis/MultivariateRealFunction.html"> + multivariate real functions</a></li> +<li><a href="../apidocs/org/apache/commons/math/optimization/DifferentiableMultivariateRealOptimizer.html"> + DifferentiableMultivariateRealOptimizer</a> for <a href="../apidocs/org/apache/commons/math/analysis/DifferentiableMultivariateRealFunction.html"> + differentiable multivariate real functions</a></li> +<li><a href="../apidocs/org/apache/commons/math/optimization/DifferentiableMultivariateVectorialOptimizer.html"> + DifferentiableMultivariateVectorialOptimizer</a> for <a href="../apidocs/org/apache/commons/math/analysis/DifferentiableMultivariateVectorialFunction.html"> + differentiable multivariate vectorial functions</a></li> +</ul> +</p> +<p> + Despite there are only four types of supported optimizers, it is possible to optimize + a transform a <a href="../apidocs/org/apache/commons/math/analysis/MultivariateVectorialFunction.html"> + non-differentiable multivariate vectorial function</a> by converting it to a <a href="../apidocs/org/apache/commons/math/analysis/MultivariateRealFunction.html"> + non-differentiable multivariate real function</a> thanks to the <a href="../apidocs/org/apache/commons/math/optimization/LeastSquaresConverter.html"> + LeastSquaresConverter</a> helper class. The transformed function can be optimized using + any implementation of the <a href="../apidocs/org/apache/commons/math/optimization/MultivariateRealOptimizer.html"> + MultivariateRealOptimizer</a> interface. + </p> +<p> + For each of the four types of supported optimizers, there is a special implementation + which wraps a classical optimizer in order to add it a multi-start feature. This feature + call the underlying optimizer several times in sequence with different starting points + and returns the best optimum found or all optima if desired. This is a classical way to + prevent being trapped into a local extremum when looking for a global one. + </p> +</div> +<div class="section"><h3><a name="a12.2_Univariate_Functions"></a>12.2 Univariate Functions</h3> +<p> + A <a href="../apidocs/org/apache/commons/math/optimization/UnivariateRealOptimizer.html"> + UnivariateRealOptimizer</a> is used to find the minimal values of a univariate real-valued + function <code>f</code>. + </p> +<p> + These algorithms usage is very similar to root-finding algorithms usage explained + in the analysis package. The main difference is that the <code>solve</code> methods in root + finding algorithms is replaced by <code>optimize</code> methods. + </p> +</div> +<div class="section"><h3><a name="a12.3_Linear_Programming"></a>12.3 Linear Programming</h3> +<p> + This package provides an implementation of George Dantzig's simplex algorithm + for solving linear optimization problems with linear equality and inequality + constraints. + </p> +</div> +<div class="section"><h3><a name="a12.4_Direct_Methods"></a>12.4 Direct Methods</h3> +<p> + Direct search methods only use cost function values, they don't + need derivatives and don't either try to compute approximation of + the derivatives. According to a 1996 paper by Margaret H. Wright + (<a href="http://cm.bell-labs.com/cm/cs/doc/96/4-02.ps.gz" class="externalLink">Direct + Search Methods: Once Scorned, Now Respectable</a>), they are used + when either the computation of the derivative is impossible (noisy + functions, unpredictable discontinuities) or difficult (complexity, + computation cost). In the first cases, rather than an optimum, a + <em>not too bad</em> point is desired. In the latter cases, an + optimum is desired but cannot be reasonably found. In all cases + direct search methods can be useful. + </p> +<p> + Simplex-based direct search methods are based on comparison of + the cost function values at the vertices of a simplex (which is a + set of n+1 points in dimension n) that is updated by the algorithms + steps. + </p> +<p> + The instances can be built either in single-start or in + multi-start mode. Multi-start is a traditional way to try to avoid + being trapped in a local minimum and miss the global minimum of a + function. It can also be used to verify the convergence of an + algorithm. In multi-start mode, the <code>minimizes</code>method + returns the best minimum found after all starts, and the <code>etMinima</code> + method can be used to retrieve all minima from all starts (including the one + already provided by the <code>minimizes</code> method). + </p> +<p> + The <code>direct</code> package provides two solvers. The first one is the classical + <a href="../apidocs/org/apache/commons/math/optimization/direct/NelderMead.html"> + Nelder-Mead</a> method. The second one is Virginia Torczon's + <a href="../apidocs/org/apache/commons/math/optimization/direct/MultiDirectional.html"> + multi-directional</a> method. + </p> +</div> +<div class="section"><h3><a name="a12.5_General_Case"></a>12.5 General Case</h3> +<p> + The general package deals with non-linear vectorial optimization problems when + the partial derivatives of the objective function are available. + </p> +<p> + One important class of estimation problems is weighted least + squares problems. They basically consist in finding the values + for some parameters p<sub>k</sub> such that a cost function + J = sum(w<sub>i</sub>(mes<sub>i</sub> - mod<sub>i</sub>)<sup>2</sup>) is + minimized. The various (target<sub>i</sub> - model<sub>i</sub>(p<sub>k</sub>)) + terms are called residuals. They represent the deviation between a set of + target values target<sub>i</sub> and theoretical values computed from + models model<sub>i</sub> depending on free parameters p<sub>k</sub>. + The w<sub>i</sub> factors are weights. One classical use case is when the + target values are experimental observations or measurements. + </p> +<p> + Solving a least-squares problem is finding the free parameters p<sub>k</sub> + of the theoretical models such that they are close to the target values, i.e. + when the residual are small. + </p> +<p> + Two optimizers are available in the general package, both devoted to least-squares + problems. The first one is based on the <a href="../apidocs/org/apache/commons/math/optimization/general/GaussNewtonOptimizer.html"> + Gauss-Newton</a> method. The second one is the <a href="../apidocs/org/apache/commons/math/optimization/general/LevenbergMarquardtOptimizer.html"> + Levenberg-Marquardt</a> method. + </p> +<p> + In order to solve a vectorial optimization problem, the user must provide it as + an object implementing the <a href="../apidocs/org/apache/commons/math/analysis/DifferentiableMultivariateVectorialFunction.html"> + DifferentiableMultivariateVectorialFunction</a> interface. The object will be provided to + the <code>estimate</code> method of the optimizer, along with the target and weight arrays, + thus allowing the optimizer to compute the residuals at will. The last parameter to the + <code>estimate</code> method is the point from which the optimizer will start its + search for the optimal point. + </p> +<p> + In addition to least squares solving, the <a href="../apidocs/org/apache/commons/math/optimization/general/NonLinearConjugateGradientOptimizer.html"> + NonLinearConjugateGradientOptimizer</a> class provides a non-linear conjugate gradient algorithm + to optimize <a href="../apidocs/org/apache/commons/math/optimization/DifferentiableMultivariateRealFunction.html"> + DifferentiableMultivariateRealFunction</a>. Both the Fletcher-Reeves and the Polak-Ribière + search direction update methods are supported. It is also possible to set up a preconditioner + or to change the line-search algorithm of the inner loop if desired (the default one is a Brent + solver). + </p> +</div> +<div class="section"><h3><a name="a12.6_Curve_Fitting"></a>12.6 Curve Fitting</h3> +<p> + The fitting package deals with curve fitting for univariate real functions. + When a univariate real function y = f(x) does depend on some unknown parameters + p<sub>0</sub>, p<sub>1</sub> ... p<sub>n-1</sub>, curve fitting can be used to + find these parameters. It does this by <em>fitting</em> the curve so it remains + very close to a set of observed points (x<sub>0</sub>, y<sub>0</sub>), + (x<sub>1</sub>, y<sub>1</sub>) ... (x<sub>k-1</sub>, y<sub>k-1</sub>). This + fitting is done by finding the parameters values that minimizes the objective + function sum(y<sub>i</sub>-f(x<sub>i</sub>))<sup>2</sup>. This is really a least + squares problem. + </p> +<p> + For all provided curve fitters, the operating principle is the same. Users must first + create an instance of the fitter, then add the observed points and once the complete + sample of observed points has been added they must call the <code>fit</code> method + which will compute the parameters that best fit the sample. A weight is associated + with each observed point, this allows to take into account uncertainty on some points + when they come from loosy measurements for example. If no such information exist and + all points should be treated the same, it is safe to put 1.0 as the weight for all points. + </p> +<p> + The <a href="../apidocs/org/apache/commons/math/optimization/fitting/CurveFitter.html"> + CurveFitter</a> class provides curve fitting for general curves. Users must + provide their own implementation of the curve template as a class implementing + the <a href="../apidocs/org/apache/commons/math/optimization/fitting/ParametricRealFunction.html"> + ParametricRealFunction</a> interface and they must provide the initial guess of the + parameters. The more specialized <a href="../apidocs/org/apache/commons/math/optimization/fitting/PolynomialFitter.html"> + PolynomialFitter</a> and <a href="../apidocs/org/apache/commons/math/optimization/fitting/HarmonicFitter.html"> + HarmonicFitter</a> classes require neither an implementation of the parametric real function + not an initial guess as they are able to compute them by themselves. + </p> +<p> + An example of fitting a polynomial is given here: + </p> +<div class="source"><pre>PolynomialFitter fitter = new PolynomialFitter(degree, new LevenbergMarquardtOptimizer()); +fitter.addObservedPoint(-1.00, 2.021170021833143); +fitter.addObservedPoint(-0.99 2.221135431136975); +fitter.addObservedPoint(-0.98 2.09985277659314); +fitter.addObservedPoint(-0.97 2.0211192647627025); +// lots of lines ommitted +fitter.addObservedPoint( 0.99, -2.4345814727089854); +PolynomialFunction fitted = fitter.fit(); + </pre> +</div> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/overview.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,281 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - User Guide - Overview</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <strong>Overview</strong> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="Overview"></a>Overview</h2> +<div class="section"><h3><a name="a0.1_About_The_User_Guide"></a>0.1 About The User Guide</h3> +<p> + This guide is intended to help programmers quickly find what they need to develop + solutions using Commons Math. It also provides a supplement to the javadoc API documentation, + providing a little more explanation of the mathematical objects and functions included + in the package. + </p> +</div> +<div class="section"><h3><a name="a0.2_Whats_in_commons-math"></a>0.2 What's in commons-math</h3> +<p> + Commons Math is made up of a small set of math/stat utilities addressing + programming problems like the ones in the list below. This list is not exhaustive, + it's just meant to give a feel for the kinds of things that Commons Math provides. + <ul><li>Computing means, variances and other summary statistics for a list of numbers</li> +<li>Fitting a line to a set of data points using linear regression</li> +<li>Finding a smooth curve that passes through a collection of points (interpolation)</li> +<li>Fitting a parametric model to a set of measurements using least-squares methods</li> +<li>Solving equations involving real-valued functions (i.e. root-finding)</li> +<li>Solving systems of linear equations</li> +<li>Solving Ordinary Differential Equations</li> +<li>Minimizing multi-dimensional functions</li> +<li>Generating random numbers with more restrictions (e.g distribution, range) than what + is possible using the JDK</li> +<li>Generating random samples and/or datasets that are "like" the data in an input file</li> +<li>Performing statistical significance tests</li> +<li>Miscellaneous mathematical functions such as factorials, binomial + coefficients and "special functions" (e.g. gamma, beta functions)</li> +</ul> +</p> +<p> + We are actively seeking ideas for additional components that fit into the + <a href="../index.html#summary">Commons Math vision</a> of a set of lightweight, + self-contained math/stat components useful for solving common programming problems. + Suggestions for new components or enhancements to existing functionality are always welcome! + All feedback/suggestions for improvement should be sent to the + <a href="http://commons.apache.org/mail-lists.html" class="externalLink">commons-dev mailing list</a> with + [math] at the beginning of the subject line. + </p> +</div> +<div class="section"><h3><a name="a0.3_How_commons-math_is_organized"></a>0.3 How commons-math is organized</h3> +<p> + Commons Math is divided into fourteen subpackages, based on functionality provided. + <ol type="1"><li><a href="stat.html">org.apache.commons.math.stat</a> - statistics, statistical tests</li> +<li><a href="analysis.html">org.apache.commons.math.analysis</a> - rootfinding, integration, interpolation, polynomials</li> +<li><a href="random.html">org.apache.commons.math.random</a> - random numbers, strings and data generation</li> +<li><a href="special.html">org.apache.commons.math.special</a> - special functions (Gamma, Beta) </li> +<li><a href="linear.html">org.apache.commons.math.linear</a> - matrices, solving linear systems </li> +<li><a href="utilities.html">org.apache.commons.math.util</a> - common math/stat functions extending java.lang.Math </li> +<li><a href="complex.html">org.apache.commons.math.complex</a> - complex numbers</li> +<li><a href="distribution.html">org.apache.commons.math.distribution</a> - probability distributions</li> +<li><a href="fraction.html">org.apache.commons.math.fraction</a> - rational numbers</li> +<li><a href="transform.html">org.apache.commons.math.transform</a> - transform methods (Fast Fourier)</li> +<li><a href="geometry.html">org.apache.commons.math.geometry</a> - 3D geometry (vectors and rotations)</li> +<li><a href="optimization.html">org.apache.commons.math.optimization</a> - function maximization or minimization</li> +<li><a href="ode.html">org.apache.commons.math.ode</a> - Ordinary Differential Equations integration</li> +<li><a href="genetics.html">org.apache.commons.math.genetics</a> - Genetic Algorithms</li> +</ol> + + Package javadocs are <a href="../apidocs/index.html">here</a></p> +</div> +<div class="section"><h3><a name="a0.4_How_interface_contracts_are_specified_in_commons-math_javadoc"></a>0.4 How interface contracts are specified in commons-math javadoc</h3> +<p> + You should always read the javadoc class and method comments carefully when using + Commons Math components in your programs. The javadoc provides references to the algorithms + that are used, usage notes about limitations, performance, etc. as well as interface contracts. + Interface contracts are specified in terms of preconditions (what has to be true in order + for the method to return valid results), special values returned (e.g. Double.NaN) + or exceptions that may be thrown if the preconditions are not met, and definitions for returned + values/objects or state changes.</p> +<p> + When the actual parameters provided to a method or the internal state of an object + make a computation meaningless, an IllegalArgumentException or IllegalStateException may + be thrown. Exact conditions under which runtime exceptions (and any other exceptions) are + thrown are specified in the javadoc method comments. In some cases, to be consistent with + the <a href="http://grouper.ieee.org/groups/754/" class="externalLink">IEEE 754 standard</a> for floating point + arithmetic and with java.lang.Math, Commons Math methods return Double.NaN values. + Conditions under which Double.NaN or other special values are returned are fully specified + in the javadoc method comments. + </p> +</div> +<div class="section"><h3><a name="a0.5_Dependencies"></a>0.5 Dependencies</h3> +<p> + Commons Math requires JDK 1.5+ and has no runtime dependencies. + </p> +</div> +<div class="section"><h3><a name="a0.6_License"></a>0.6 License</h3> +<p> + Commons Math is distributed under the terms of the Apache License, Version 2.0: + <a href="http://www.apache.org/licenses/LICENSE-2.0" class="externalLink"></a>. + </p> +<p> + This product includes software developed by the University of Chicago, as Operator + of Argonne National Laboratory. This corresponds to software translated from the lmder, + lmpar and qrsolv Fortran routines from the Minpack package and distributed under the + following disclaimer: <a href="http://www.netlib.org/minpack/disclaimer" class="externalLink"></a>. + </p> +<p> + This product includes software translated from the odex Fortran routine developed by + E. Hairer and G. Wanner and distributed under the following license: + <a href="http://www.unige.ch/~hairer/prog/licence.txt" class="externalLink"></a>. + </p> +<p> + This product includes software translated from some LAPACK Fortran routines and + distributed under the following license: <a href="http://www.netlib.org/lapack/LICENSE" class="externalLink"></a>. + </p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/random.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,530 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Data Generation</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <strong>Data Generation</strong> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a2_Data_Generation"></a>2 Data Generation</h2> +<div class="section"><h3><a name="a2.1_Overview"></a>2.1 Overview</h3> +<p> + The Commons Math random package includes utilities for + <ul><li>generating random numbers</li> +<li>generating random strings</li> +<li>generating cryptographically secure sequences of random numbers or + strings</li> +<li>generating random samples and permutations</li> +<li>analyzing distributions of values in an input file and generating + values "like" the values in the file</li> +<li>generating data for grouped frequency distributions or + histograms</li> +</ul> +</p> +<p> + The source of random data used by the data generation utilities is + pluggable. By default, the JDK-supplied PseudoRandom Number Generator + (PRNG) is used, but alternative generators can be "plugged in" using an + adaptor framework, which provides a generic facility for replacing + <code>java.util.Random</code> with an alternative PRNG. Another very + good PRNG suitable for Monte-Carlo analysis (but <strong>not</strong> + for cryptography) provided by the library is the Mersenne twister from + Makoto Matsumoto and Takuji Nishimura + </p> +<p> + Sections 2.2-2.6 below show how to use the commons math API to generate + different kinds of random data. The examples all use the default + JDK-supplied PRNG. PRNG pluggability is covered in 2.7. The only + modification required to the examples to use alternative PRNGs is to + replace the argumentless constructor calls with invocations including + a <code>RandomGenerator</code> instance as a parameter. + </p> +</div> +<div class="section"><h3><a name="a2.2_Random_numbers"></a>2.2 Random numbers</h3> +<p> + The <a href="../apidocs/org/apache/commons/math/random/RandomData.html"> + org.apache.commons.math.RandomData</a> interface defines methods for + generating random sequences of numbers. The API contracts of these methods + use the following concepts: + <dl><dt>Random sequence of numbers from a probability distribution</dt> +<dd>There is no such thing as a single "random number." What can be + generated are <i>sequences</i> of numbers that appear to be random. When + using the built-in JDK function <code>Math.random(),</code> sequences of + values generated follow the + <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm" class="externalLink"> + Uniform Distribution</a>, which means that the values are evenly spread + over the interval between 0 and 1, with no sub-interval having a greater + probability of containing generated values than any other interval of the + same length. The mathematical concept of a + <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda36.htm" class="externalLink"> + probability distribution</a> basically amounts to asserting that different + ranges in the set of possible values of a random variable have + different probabilities of containing the value. Commons Math supports + generating random sequences from the following probability distributions. + The javadoc for the <code>nextXxx</code> methods in + <code>RandomDataImpl</code> describes the algorithms used to generate + random deviates from each of these distributions. + <ul><li><a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm" class="externalLink"> + uniform distribution</a></li> +<li><a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm" class="externalLink"> + exponential distribution</a></li> +<li><a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm" class="externalLink"> + poisson distribution</a></li> +<li><a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm" class="externalLink"> + Gaussian distribution</a></li> +</ul> +</dd> +<dt>Cryptographically secure random sequences</dt> +<dd>It is possible for a sequence of numbers to appear random, but + nonetheless to be predictable based on the algorithm used to generate the + sequence. If in addition to randomness, strong unpredictability is + required, it is best to use a + <a href="http://www.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator" class="externalLink"> + secure random number generator</a> to generate values (or strings). The + nextSecureXxx methods in the <code>RandomDataImpl</code> implementation of + the <code>RandomData</code> interface use the JDK <code>SecureRandom</code> + PRNG to generate cryptographically secure sequences. The + <code>setSecureAlgorithm</code> method allows you to change the underlying + PRNG. These methods are <strong>much slower</strong> than the corresponding + "non-secure" versions, so they should only be used when cryptographic + security is required.</dd> +<dt>Seeding pseudo-random number generators</dt> +<dd>By default, the implementation provided in <code>RandomDataImpl</code> + uses the JDK-provided PRNG. Like most other PRNGs, the JDK generator + generates sequences of random numbers based on an initial "seed value". + For the non-secure methods, starting with the same seed always produces the + same sequence of values. Secure sequences started with the same seeds will + diverge. When a new <code>RandomDataImpl</code> is created, the underlying + random number generators are <strong>not</strong> initialized. The first + call to a data generation method, or to a <code>reSeed()</code> method + initializes the appropriate generator. If you do not explicitly seed the + generator, it is by default seeded with the current time in milliseconds. + Therefore, to generate sequences of random data values, you should always + instantiate <strong>one</strong><code>RandomDataImpl</code> and use it + repeatedly instead of creating new instances for subsequent values in the + sequence. For example, the following will generate a random sequence of 50 + long integers between 1 and 1,000,000, using the current time in + milliseconds as the seed for the JDK PRNG: + <div class="source"><pre> +RandomData randomData = new RandomDataImpl(); +for (int i = 0; i < 1000; i++) { + value = randomData.nextLong(1, 1000000); +} + </pre> +</div> + + The following will not in general produce a good random sequence, since the + PRNG is reseeded each time through the loop with the current time in + milliseconds: + <div class="source"><pre> +for (int i = 0; i < 1000; i++) { + RandomDataImpl randomData = new RandomDataImpl(); + value = randomData.nextLong(1, 1000000); +} + </pre> +</div> + + The following will produce the same random sequence each time it is + executed: + <div class="source"><pre> +RandomData randomData = new RandomDataImpl(); +randomData.reSeed(1000); +for (int i = 0; i = 1000; i++) { + value = randomData.nextLong(1, 1000000); +} + </pre> +</div> + + The following will produce a different random sequence each time it is + executed. + <div class="source"><pre> +RandomData randomData = new RandomDataImpl(); +randomData.reSeedSecure(1000); +for (int i = 0; i < 1000; i++) { + value = randomData.nextSecureLong(1, 1000000); +} + </pre> +</div> +</dd> +</dl> +</p> +</div> +<div class="section"><h3><a name="a2.3_Random_Vectors"></a>2.3 Random Vectors</h3> +<p> + Some algorithm requires random vectors instead of random scalars. When the + components of these vectors are uncorrelated, they may be generated simply + one at a time and packed together in the vector. The <a href="../apidocs/org/apache/commons/math/random/UncorrelatedRandomVectorGenerator.html"> + org.apache.commons.math.UncorrelatedRandomVectorGenerator</a> class + does however simplify this process by setting the mean and deviation of each + component once and generating complete vectors. When the components are correlated + however, generating them is much more difficult. The <a href="../apidocs/org/apache/commons/math/random/CorrelatedRandomVectorGenerator.html"> + org.apache.commons.math.CorrelatedRandomVectorGenerator</a> class + provides this service. In this case, the user must set up a complete covariance matrix + instead of a simple standard deviations vector. This matrix gathers both the variance + and the correlation information of the probability law. + </p> +<p> + The main use for correlated random vector generation is for Monte-Carlo + simulation of physical problems with several variables, for example to + generate error vectors to be added to a nominal vector. A particularly + common case is when the generated vector should be drawn from a <a href="http://en.wikipedia.org/wiki/Multivariate_normal_distribution" class="externalLink"> + Multivariate Normal Distribution</a>. + </p> +</div> +<div class="section"><h3><a name="a2.4_Random_Strings"></a>2.4 Random Strings</h3> +<p> + The methods <code>nextHexString</code> and <code>nextSecureHexString</code> + can be used to generate random strings of hexadecimal characters. Both + of these methods produce sequences of strings with good dispersion + properties. The difference between the two methods is that the second is + cryptographically secure. Specifically, the implementation of + <code>nextHexString(n)</code> in <code>RandomDataImpl</code> uses the + following simple algorithm to generate a string of <code>n</code> hex digits: + <ol type="1"><li>n/2+1 binary bytes are generated using the underlying Random</li> +<li>Each binary byte is translated into 2 hex digits</li> +</ol> + + The <code>RandomDataImpl</code> implementation of the "secure" version, + <code>nextSecureHexString</code> generates hex characters in 40-byte + "chunks" using a 3-step process: + <ol type="1"><li>20 random bytes are generated using the underlying + <code>SecureRandom.</code></li> +<li>SHA-1 hash is applied to yield a 20-byte binary digest.</li> +<li>Each byte of the binary digest is converted to 2 hex digits</li> +</ol> + + Similarly to the secure random number generation methods, + <code>nextSecureHexString</code> is <strong>much slower</strong> than + the non-secure version. It should be used only for applications such as + generating unique session or transaction ids where predictability of + subsequent ids based on observation of previous values is a security + concern. If all that is needed is an even distribution of hex characters + in the generated strings, the non-secure method should be used. + </p> +</div> +<div class="section"><h3><a name="a2.5_Random_permutations_combinations_sampling"></a>2.5 Random permutations, combinations, sampling</h3> +<p> + To select a random sample of objects in a collection, you can use the + <code>nextSample</code> method in the <code>RandomData</code> interface. + Specifically, if <code>c</code> is a collection containing at least + <code>k</code> objects, and <code>randomData</code> is a + <code>RandomData</code> instance <code>randomData.nextSample(c, k)</code> + will return an <code>object[]</code> array of length <code>k</code> + consisting of elements randomly selected from the collection. If + <code>c</code> contains duplicate references, there may be duplicate + references in the returned array; otherwise returned elements will be + unique -- i.e., the sampling is without replacement among the object + references in the collection. </p> +<p> + If <code>randomData</code> is a <code>RandomData</code> instance, and + <code>n</code> and <code>k</code> are integers with + <code> k <= n</code>, then + <code>randomData.nextPermutation(n, k)</code> returns an <code>int[]</code> + array of length <code>k</code> whose whose entries are selected randomly, + without repetition, from the integers <code>0</code> through + <code>n-1</code> (inclusive), i.e., + <code>randomData.nextPermutation(n, k)</code> returns a random + permutation of <code>n</code> taken <code>k</code> at a time. + </p> +</div> +<div class="section"><h3><a name="a2.6_Generating_data_like_an_input_file"></a>2.6 Generating data 'like' an input file</h3> +<p> + Using the <code>ValueServer</code> class, you can generate data based on + the values in an input file in one of two ways: + <dl><dt>Replay Mode</dt> +<dd> The following code will read data from <code>url</code> + (a <code>java.net.URL</code> instance), cycling through the values in the + file in sequence, reopening and starting at the beginning again when all + values have been read. + <div class="source"><pre> + ValueServer vs = new ValueServer(); + vs.setValuesFileURL(url); + vs.setMode(ValueServer.REPLAY_MODE); + vs.resetReplayFile(); + double value = vs.getNext(); + // ...Generate and use more values... + vs.closeReplayFile(); + </pre> +</div> + + The values in the file are not stored in memory, so it does not matter + how large the file is, but you do need to explicitly close the file + as above. The expected file format is \n -delimited (i.e. one per line) + strings representing valid floating point numbers. + </dd> +<dt>Digest Mode</dt> +<dd>When used in Digest Mode, the ValueServer reads the entire input file + and estimates a probability density function based on data from the file. + The estimation method is essentially the + <a href="http://nedwww.ipac.caltech.edu/level5/March02/Silverman/Silver2_6.html" class="externalLink"> + Variable Kernel Method</a> with Gaussian smoothing. Once the density + has been estimated, <code>getNext()</code> returns random values whose + probability distribution matches the empirical distribution -- i.e., if + you generate a large number of such values, their distribution should + "look like" the distribution of the values in the input file. The values + are not stored in memory in this case either, so there is no limit to the + size of the input file. Here is an example: + <div class="source"><pre> + ValueServer vs = new ValueServer(); + vs.setValuesFileURL(url); + vs.setMode(ValueServer.DIGEST_MODE); + vs.computeDistribution(500); //Read file and estimate distribution using 500 bins + double value = vs.getNext(); + // ...Generate and use more values... + </pre> +</div> + + See the javadoc for <code>ValueServer</code> and + <code>EmpiricalDistribution</code> for more details. Note that + <code>computeDistribution()</code> opens and closes the input file + by itself. + </dd> +</dl> +</p> +</div> +<div class="section"><h3><a name="a2.7_PRNG_Pluggability"></a>2.7 PRNG Pluggability</h3> +<p> + To enable alternative PRNGs to be "plugged in" to the commons-math data + generation utilities and to provide a generic means to replace + <code>java.util.Random</code> in applications, a random generator + adaptor framework has been added to commons-math. The + <a href="../apidocs/org/apache/commons/math/random/RandomGenerator.html"> + org.apache.commons.math.RandomGenerator</a> interface abstracts the public + interface of <code>java.util.Random</code> and any implementation of this + interface can be used as the source of random data for the commons-math + data generation classes. An abstract base class, + <a href="../apidocs/org/apache/commons/math/random/AbstractRandomGenerator.html"> + org.apache.commons.math.AbstractRandomGenerator</a> is provided to make + implementation easier. This class provides default implementations of + "derived" data generation methods based on the primitive, + <code>nextDouble().</code> To support generic replacement of + <code>java.util.Random</code>, the + <a href="../apidocs/org/apache/commons/math/random/RandomAdaptor.html"> + org.apache.commons.math.RandomAdaptor</a> class is provided, which + extends <code>java.util.Random</code> and wraps and delegates calls to + a <code>RandomGenerator</code> instance. + </p> +<p> + Examples: + <dl><dt>Create a RandomGenerator based on RngPack's Mersenne Twister</dt> +<dd>To create a RandomGenerator using the RngPack Mersenne Twister PRNG + as the source of randomness, extend <code>AbstractRandomGenerator</code> + overriding the derived methods that the RngPack implementation provides: + <div class="source"><pre> +import edu.cornell.lassp.houle.RngPack.RanMT; +/** + * AbstractRandomGenerator based on RngPack RanMT generator. + */ +public class RngPackGenerator extends AbstractRandomGenerator { + + private RanMT random = new RanMT(); + + public void setSeed(long seed) { + random = new RanMT(seed); + } + + public double nextDouble() { + return random.raw(); + } + + public double nextGaussian() { + return random.gaussian(); + } + + public int nextInt(int n) { + return random.choose(n); + } + + public boolean nextBoolean() { + return random.coin(); + } +} + </pre> +</div> +</dd> +<dt>Use the Mersenne Twister RandomGenerator in place of + <code>java.util.Random</code> in <code>RandomData</code></dt> +<dd><div class="source"><pre> +RandomData randomData = new RandomDataImpl(new RngPackGenerator()); + </pre> +</div> +</dd> +<dt>Create an adaptor instance based on the Mersenne Twister generator + that can be used in place of a <code>Random</code></dt> +<dd><div class="source"><pre> + RandomGenerator generator = new RngPackGenerator(); + Random random = RandomAdaptor.createAdaptor(generator); + // random can now be used in place of a Random instance, data generation + // calls will be delegated to the wrapped Mersenne Twister + </pre> +</div> +</dd> +</dl> +</p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/special.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,230 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Special Functions</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <strong>Special Functions</strong> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a5_Special_Functions"></a>5 Special Functions</h2> +<div class="section"><h3><a name="a5.1_Overview"></a>5.1 Overview</h3> +<p> + The special functions portion of Commons-Math contains several useful functions not + provided by <code>java.lang.Math</code>. These functions mostly serve as building blocks + for other portions of Commons-Math but, as others may find them useful as stand-alone + methods, these special functions were included as part of the Commons-Math public API. + </p> +</div> +<div class="section"><h3><a name="a5.2_Erf_functions"></a>5.2 Erf functions</h3> +<p><code>org.apache.commons.math.special.Erf</code> contains several useful functions involving the Error Function, Erf. + <table class="bodyTable"><tr class="a"><th>Function</th> +<th>Method</th> +<th>Reference</th> +</tr> +<tr class="b"><td>Error Function</td> +<td>erf</td> +<td>See <a href="http://mathworld.wolfram.com/Erf.html" class="externalLink">Erf</a> from MathWorld</td> +</tr> +</table> +</p> +</div> +<div class="section"><h3><a name="a5.3_Gamma_functions"></a>5.3 Gamma functions</h3> +<p><code>org.apache.commons.math.special.Gamma</code> contains several useful functions involving the Gamma Function. + <table class="bodyTable"><tr class="a"><th>Function</th> +<th>Method</th> +<th>Reference</th> +</tr> +<tr class="b"><td>Log Gamma</td> +<td>logGamma</td> +<td>See <a href="http://mathworld.wolfram.com/GammaFunction.html" class="externalLink">Gamma Function</a> from MathWorld</td> +</tr> +<tr class="a"><td>Regularized Gamma</td> +<td>regularizedGammaP</td> +<td>See <a href="http://mathworld.wolfram.com/RegularizedGammaFunction.html" class="externalLink">Regularized Gamma Function</a> from MathWorld</td> +</tr> +</table> +</p> +</div> +<div class="section"><h3><a name="a5.4_Beta_funtions"></a>5.4 Beta funtions</h3> +<p><code>org.apache.commons.math.special.Beta</code> contains several useful functions involving the Beta Function. + <table class="bodyTable"><tr class="b"><th>Function</th> +<th>Method</th> +<th>Reference</th> +</tr> +<tr class="a"><td>Log Beta</td> +<td>logBeta</td> +<td>See <a href="http://mathworld.wolfram.com/BetaFunction.html" class="externalLink">Beta Function</a> from MathWorld</td> +</tr> +<tr class="b"><td>Regularized Beta</td> +<td>regularizedBeta</td> +<td>See <a href="http://mathworld.wolfram.com/RegularizedBetaFunction.html" class="externalLink">Regularized Beta Function</a> from MathWorld</td> +</tr> +</table> +</p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/stat.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,1227 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Statistics</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <strong>Statistics</strong> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a1_Statistics"></a>1 Statistics</h2> +<div class="section"><h3><a name="a1.1_Overview"></a>1.1 Overview</h3> +<p> + The statistics package provides frameworks and implementations for + basic Descriptive statistics, frequency distributions, bivariate regression, + and t-, chi-square and ANOVA test statistics. + </p> +<p><a href="#a1.2_Descriptive_statistics">Descriptive statistics</a><br /> +</br><a href="#a1.3_Frequency_distributions">Frequency distributions</a><br /> +</br><a href="#a1.4_Simple_regression">Simple Regression</a><br /> +</br><a href="#a1.5_Multiple_linear_regression">Multiple Regression</a><br /> +</br><a href="#a1.6_Rank_transformations">Rank transformations</a><br /> +</br><a href="#a1.7_Covariance_and_correlation">Covariance and correlation</a><br /> +</br><a href="#a1.8_Statistical_tests">Statistical Tests</a><br /> +</br></p> +</div> +<div class="section"><h3><a name="a1.2_Descriptive_statistics"></a>1.2 Descriptive statistics</h3> +<p> + The stat package includes a framework and default implementations for + the following Descriptive statistics: + <ul><li>arithmetic and geometric means</li> +<li>variance and standard deviation</li> +<li>sum, product, log sum, sum of squared values</li> +<li>minimum, maximum, median, and percentiles</li> +<li>skewness and kurtosis</li> +<li>first, second, third and fourth moments</li> +</ul> +</p> +<p> + With the exception of percentiles and the median, all of these + statistics can be computed without maintaining the full list of input + data values in memory. The stat package provides interfaces and + implementations that do not require value storage as well as + implementations that operate on arrays of stored values. + </p> +<p> + The top level interface is + <a href="../apidocs/org/apache/commons/math/stat/descriptive/UnivariateStatistic.html"> + org.apache.commons.math.stat.descriptive.UnivariateStatistic.</a> + This interface, implemented by all statistics, consists of + <code>evaluate()</code> methods that take double[] arrays as arguments + and return the value of the statistic. This interface is extended by + <a href="../apidocs/org/apache/commons/math/stat/descriptive/StorelessUnivariateStatistic.html"> + StorelessUnivariateStatistic</a>, which adds <code>increment(),</code><code>getResult()</code> and associated methods to support + "storageless" implementations that maintain counters, sums or other + state information as values are added using the <code>increment()</code> + method. + </p> +<p> + Abstract implementations of the top level interfaces are provided in + <a href="../apidocs/org/apache/commons/math/stat/descriptive/AbstractUnivariateStatistic.html"> + AbstractUnivariateStatistic</a> and + <a href="../apidocs/org/apache/commons/math/stat/descriptive/AbstractStorelessUnivariateStatistic.html"> + AbstractStorelessUnivariateStatistic</a> respectively. + </p> +<p> + Each statistic is implemented as a separate class, in one of the + subpackages (moment, rank, summary) and each extends one of the abstract + classes above (depending on whether or not value storage is required to + compute the statistic). There are several ways to instantiate and use statistics. + Statistics can be instantiated and used directly, but it is generally more convenient + (and efficient) to access them using the provided aggregates, + <a href="../apidocs/org/apache/commons/math/stat/descriptive/DescriptiveStatistics.html"> + DescriptiveStatistics</a> and + <a href="../apidocs/org/apache/commons/math/stat/descriptive/SummaryStatistics.html"> + SummaryStatistics.</a></p> +<p><code>DescriptiveStatistics</code> maintains the input data in memory + and has the capability of producing "rolling" statistics computed from a + "window" consisting of the most recently added values. + </p> +<p><code>SummaryStatistics</code> does not store the input data values + in memory, so the statistics included in this aggregate are limited to those + that can be computed in one pass through the data without access to + the full array of values. + </p> +<p><table class="bodyTable"><tr class="a"><th>Aggregate</th> +<th>Statistics Included</th> +<th>Values stored?</th> +<th>"Rolling" capability?</th> +</tr> +<tr class="b"><td><a href="../apidocs/org/apache/commons/math/stat/descriptive/DescriptiveStatistics.html"> + DescriptiveStatistics</a></td> +<td>min, max, mean, geometric mean, n, + sum, sum of squares, standard deviation, variance, percentiles, skewness, + kurtosis, median</td> +<td>Yes</td> +<td>Yes</td> +</tr> +<tr class="a"><td><a href="../apidocs/org/apache/commons/math/stat/descriptive/SummaryStatistics.html"> + SummaryStatistics</a></td> +<td>min, max, mean, geometric mean, n, + sum, sum of squares, standard deviation, variance</td> +<td>No</td> +<td>No</td> +</tr> +</table> +</p> +<p><code>SummaryStatistics</code> can be aggregated using + <a href="../apidocs/org/apache/commons/math/stat/descriptive/AggregateSummaryStatistics.html"> + AggregateSummaryStatistics.</a> This class can be used to concurrently gather statistics for multiple + datasets as well as for a combined sample including all of the data. + </p> +<p><code>MultivariateSummaryStatistics</code> is similar to <code>SummaryStatistics</code> + but handles n-tuple values instead of scalar values. It can also compute the + full covariance matrix for the input data. + </p> +<p> + Neither <code>DescriptiveStatistics</code> nor <code>SummaryStatistics</code> is + thread-safe. <a href="../apidocs/org/apache/commons/math/stat/descriptive/SynchronizedDescriptiveStatistics.html"> + SynchronizedDescriptiveStatistics</a> and + <a href="../apidocs/org/apache/commons/math/stat/descriptive/SynchronizedSummaryStatistics.html"> + SynchronizedSummaryStatistics</a>, respectively, provide thread-safe versions for applications that + require concurrent access to statistical aggregates by multiple threads. + <a href="../apidocs/org/apache/commons/math/stat/descriptive/SynchronizedMultiVariateSummaryStatistics.html"> + SynchronizedMultivariateSummaryStatistics</a> provides threadsafe <code>MultivariateSummaryStatistics.</code></p> +<p> + There is also a utility class, + <a href="../apidocs/org/apache/commons/math/stat/StatUtils.html"> + StatUtils</a>, that provides static methods for computing statistics + directly from double[] arrays. + </p> +<p> + Here are some examples showing how to compute Descriptive statistics. + <dl><dt>Compute summary statistics for a list of double values</dt> +<br /> +</br><dd>Using the <code>DescriptiveStatistics</code> aggregate + (values are stored in memory): + <div class="source"><pre> +// Get a DescriptiveStatistics instance +DescriptiveStatistics stats = new DescriptiveStatistics(); + +// Add the data from the array +for( int i = 0; i < inputArray.length; i++) { + stats.addValue(inputArray[i]); +} + +// Compute some statistics +double mean = stats.getMean(); +double std = stats.getStandardDeviation(); +double median = stats.getMedian(); + </pre> +</div> +</dd> +<dd>Using the <code>SummaryStatistics</code> aggregate (values are + <strong>not</strong> stored in memory): + <div class="source"><pre> +// Get a SummaryStatistics instance +SummaryStatistics stats = new SummaryStatistics(); + +// Read data from an input stream, +// adding values and updating sums, counters, etc. +while (line != null) { + line = in.readLine(); + stats.addValue(Double.parseDouble(line.trim())); +} +in.close(); + +// Compute the statistics +double mean = stats.getMean(); +double std = stats.getStandardDeviation(); +//double median = stats.getMedian(); <-- NOT AVAILABLE + </pre> +</div> +</dd> +<dd>Using the <code>StatUtils</code> utility class: + <div class="source"><pre> +// Compute statistics directly from the array +// assume values is a double[] array +double mean = StatUtils.mean(values); +double std = StatUtils.variance(values); +double median = StatUtils.percentile(50); + +// Compute the mean of the first three values in the array +mean = StatUtils.mean(values, 0, 3); + </pre> +</div> +</dd> +<dt>Maintain a "rolling mean" of the most recent 100 values from + an input stream</dt> +<br /> +</br><dd>Use a <code>DescriptiveStatistics</code> instance with + window size set to 100 + <div class="source"><pre> +// Create a DescriptiveStats instance and set the window size to 100 +DescriptiveStatistics stats = new DescriptiveStatistics(); +stats.setWindowSize(100); + +// Read data from an input stream, +// displaying the mean of the most recent 100 observations +// after every 100 observations +long nLines = 0; +while (line != null) { + line = in.readLine(); + stats.addValue(Double.parseDouble(line.trim())); + if (nLines == 100) { + nLines = 0; + System.out.println(stats.getMean()); + } +} +in.close(); + </pre> +</div> +</dd> +<dt>Compute statistics in a thread-safe manner</dt> +<br /> +<dd>Use a <code>SynchronizedDescriptiveStatistics</code> instance + <div class="source"><pre> +// Create a SynchronizedDescriptiveStatistics instance and +// use as any other DescriptiveStatistics instance +DescriptiveStatistics stats = new SynchronizedDescriptiveStatistics(); + </pre> +</div> +</dd> +<dt>Compute statistics for multiple samples and overall statistics concurrently</dt> +<br /> +<dd>There are two ways to do this using <code>AggregateSummaryStatistics.</code> + The first is to use an <code>AggregateSummaryStatistics</code> instance to accumulate + overall statistics contributed by <code>SummaryStatistics</code> instances created using + <a href="../apidocs/org/apache/commons/math/stat/descriptive/AggregateSummaryStatistics.html#createContributingStatistics()"> + AggregateSummaryStatistics.createContributingStatistics()</a>: + <div class="source"><pre> +// Create a AggregateSummaryStatistics instance to accumulate the overall statistics +// and AggregatingSummaryStatistics for the subsamples +AggregateSummaryStatistics aggregate = new AggregateSummaryStatistics(); +SummaryStatistics setOneStats = aggregate.createContributingStatistics(); +SummaryStatistics setTwoStats = aggregate.createContributingStatistics(); +// Add values to the subsample aggregates +setOneStats.addValue(2); +setOneStats.addValue(3); +setTwoStats.addValue(2); +setTwoStats.addValue(4); +... +// Full sample data is reported by the aggregate +double totalSampleSum = aggregate.getSum(); + </pre> +</div> + + The above approach has the disadvantages that the <code>addValue</code> calls must be synchronized on the + <code>SummaryStatistics</code> instance maintained by the aggregate and each value addition updates the + aggregate as well as the subsample. For applications that can wait to do the aggregation until all values + have been added, a static + <a href="../apidocs/org/apache/commons/math/stat/descriptive/AggregateSummaryStatistics.html#aggregate(java.util.Collection)"> + aggregate</a> method is available, as shown in the following example. + This method should be used when aggregation needs to be done across threads. + <div class="source"><pre> +// Create SummaryStatistics instances for the subsample data +SummaryStatistics setOneStats = new SummaryStatistics(); +SummaryStatistics setTwoStats = new SummaryStatistics(); +// Add values to the subsample SummaryStatistics instances +setOneStats.addValue(2); +setOneStats.addValue(3); +setTwoStats.addValue(2); +setTwoStats.addValue(4); +... +// Aggregate the subsample statistics +Collection<SummaryStatistics> aggregate = new ArrayList<SummaryStatistics>(); +aggregate.add(setOneStats); +aggregate.add(setTwoStats); +StatisticalSummary aggregatedStats = AggregateSummaryStatistics.aggregate(aggregate); + +// Full sample data is reported by aggregatedStats +double totalSampleSum = aggregatedStats.getSum(); + </pre> +</div> +</dd> +</dl> +</p> +</div> +<div class="section"><h3><a name="a1.3_Frequency_distributions"></a>1.3 Frequency distributions</h3> +<p><a href="../apidocs/org/apache/commons/math/stat/Frequency.html"> + org.apache.commons.math.stat.descriptive.Frequency</a> + provides a simple interface for maintaining counts and percentages of discrete + values. + </p> +<p> + Strings, integers, longs and chars are all supported as value types, + as well as instances of any class that implements <code>Comparable.</code> + The ordering of values used in computing cumulative frequencies is by + default the <i>natural ordering,</i> but this can be overriden by supplying a + <code>Comparator</code> to the constructor. Adding values that are not + comparable to those that have already been added results in an + <code>IllegalArgumentException.</code></p> +<p> + Here are some examples. + <dl><dt>Compute a frequency distribution based on integer values</dt> +<br /> +</br><dd>Mixing integers, longs, Integers and Longs: + <div class="source"><pre> + Frequency f = new Frequency(); + f.addValue(1); + f.addValue(new Integer(1)); + f.addValue(new Long(1)); + f.addValue(2); + f.addValue(new Integer(-1)); + System.out.prinltn(f.getCount(1)); // displays 3 + System.out.println(f.getCumPct(0)); // displays 0.2 + System.out.println(f.getPct(new Integer(1))); // displays 0.6 + System.out.println(f.getCumPct(-2)); // displays 0 + System.out.println(f.getCumPct(10)); // displays 1 + </pre> +</div> +</dd> +<dt>Count string frequencies</dt> +<br /> +</br><dd>Using case-sensitive comparison, alpha sort order (natural comparator): + <div class="source"><pre> +Frequency f = new Frequency(); +f.addValue("one"); +f.addValue("One"); +f.addValue("oNe"); +f.addValue("Z"); +System.out.println(f.getCount("one")); // displays 1 +System.out.println(f.getCumPct("Z")); // displays 0.5 +System.out.println(f.getCumPct("Ot")); // displays 0.25 + </pre> +</div> +</dd> +<dd>Using case-insensitive comparator: + <div class="source"><pre> +Frequency f = new Frequency(String.CASE_INSENSITIVE_ORDER); +f.addValue("one"); +f.addValue("One"); +f.addValue("oNe"); +f.addValue("Z"); +System.out.println(f.getCount("one")); // displays 3 +System.out.println(f.getCumPct("z")); // displays 1 + </pre> +</div> +</dd> +</dl> +</p> +</div> +<div class="section"><h3><a name="a1.4_Simple_regression"></a>1.4 Simple regression</h3> +<p><a href="../apidocs/org/apache/commons/math/stat/regression/SimpleRegression.html"> + org.apache.commons.math.stat.regression.SimpleRegression</a> + provides ordinary least squares regression with one independent variable, + estimating the linear model: + </p> +<p><code> y = intercept + slope * x </code></p> +<p> + Standard errors for <code>intercept</code> and <code>slope</code> are + available as well as ANOVA, r-square and Pearson's r statistics. + </p> +<p> + Observations (x,y pairs) can be added to the model one at a time or they + can be provided in a 2-dimensional array. The observations are not stored + in memory, so there is no limit to the number of observations that can be + added to the model. + </p> +<p><strong>Usage Notes</strong>: <ul><li> When there are fewer than two observations in the model, or when + there is no variation in the x values (i.e. all x values are the same) + all statistics return <code>NaN</code>. At least two observations with + different x coordinates are requred to estimate a bivariate regression + model.</li> +<li> getters for the statistics always compute values based on the current + set of observations -- i.e., you can get statistics, then add more data + and get updated statistics without using a new instance. There is no + "compute" method that updates all statistics. Each of the getters performs + the necessary computations to return the requested statistic.</li> +</ul> +</p> +<p><strong>Implementation Notes</strong>: <ul><li> As observations are added to the model, the sum of x values, y values, + cross products (x times y), and squared deviations of x and y from their + respective means are updated using updating formulas defined in + "Algorithms for Computing the Sample Variance: Analysis and + Recommendations", Chan, T.F., Golub, G.H., and LeVeque, R.J. + 1983, American Statistician, vol. 37, pp. 242-247, referenced in + Weisberg, S. "Applied Linear Regression". 2nd Ed. 1985. All regression + statistics are computed from these sums.</li> +<li> Inference statistics (confidence intervals, parameter significance levels) + are based on on the assumption that the observations included in the model are + drawn from a <a href="http://mathworld.wolfram.com/BivariateNormalDistribution.html" class="externalLink"> + Bivariate Normal Distribution</a></li> +</ul> +</p> +<p> + Here are some examples. + <dl><dt>Estimate a model based on observations added one at a time</dt> +<br /> +</br><dd>Instantiate a regression instance and add data points + <div class="source"><pre> +regression = new SimpleRegression(); +regression.addData(1d, 2d); +// At this point, with only one observation, +// all regression statistics will return NaN + +regression.addData(3d, 3d); +// With only two observations, +// slope and intercept can be computed +// but inference statistics will return NaN + +regression.addData(3d, 3d); +// Now all statistics are defined. + </pre> +</div> +</dd> +<dd>Compute some statistics based on observations added so far + <div class="source"><pre> +System.out.println(regression.getIntercept()); +// displays intercept of regression line + +System.out.println(regression.getSlope()); +// displays slope of regression line + +System.out.println(regression.getSlopeStdErr()); +// displays slope standard error + </pre> +</div> +</dd> +<dd>Use the regression model to predict the y value for a new x value + <div class="source"><pre> +System.out.println(regression.predict(1.5d) +// displays predicted y value for x = 1.5 + </pre> +</div> + + More data points can be added and subsequent getXxx calls will incorporate + additional data in statistics. + </dd> +<dt>Estimate a model from a double[][] array of data points</dt> +<br /> +</br><dd>Instantiate a regression object and load dataset + <div class="source"><pre> +double[][] data = { { 1, 3 }, {2, 5 }, {3, 7 }, {4, 14 }, {5, 11 }}; +SimpleRegression regression = new SimpleRegression(); +regression.addData(data); + </pre> +</div> +</dd> +<dd>Estimate regression model based on data + <div class="source"><pre> +System.out.println(regression.getIntercept()); +// displays intercept of regression line + +System.out.println(regression.getSlope()); +// displays slope of regression line + +System.out.println(regression.getSlopeStdErr()); +// displays slope standard error + </pre> +</div> + + More data points -- even another double[][] array -- can be added and subsequent + getXxx calls will incorporate additional data in statistics. + </dd> +</dl> +</p> +</div> +<div class="section"><h3><a name="a1.5_Multiple_linear_regression"></a>1.5 Multiple linear regression</h3> +<p><a href="../apidocs/org/apache/commons/math/stat/regression/MultipleLinearRegression.html"> + org.apache.commons.math.stat.regression.MultipleLinearRegression</a> + provides ordinary least squares regression with a generic multiple variable linear model, which + in matrix notation can be expressed as: + </p> +<p><code> y=X*b+u </code></p> +<p> + where y is an <code>n-vector</code><b>regressand</b>, X is a <code>[n,k]</code> matrix whose <code>k</code> columns are called + <b>regressors</b>, b is <code>k-vector</code> of <b>regression parameters</b> and <code>u</code> is an <code>n-vector</code> + of <b>error terms</b> or <b>residuals</b>. The notation is quite standard in literature, + cf eg <a href="http://www.econ.queensu.ca/ETM" class="externalLink">Davidson and MacKinnon, Econometrics Theory and Methods, 2004</a>. + </p> +<p> + Two implementations are provided: <a href="../apidocs/org/apache/commons/math/stat/regression/OLSMultipleLinearRegression.html"> + org.apache.commons.math.stat.regression.OLSMultipleLinearRegression</a> and + <a href="../apidocs/org/apache/commons/math/stat/regression/GLSMultipleLinearRegression.html"> + org.apache.commons.math.stat.regression.GLSMultipleLinearRegression</a></p> +<p> + Observations (x,y and covariance data matrices) can be added to the model via the <code>addData(double[] y, double[][] x, double[][] covariance)</code> method. + The observations are stored in memory until the next time the addData method is invoked. + </p> +<p><strong>Usage Notes</strong>: <ul><li> Data is validated when invoking the <code>addData(double[] y, double[][] x, double[][] covariance)</code> method and + <code>IllegalArgumentException</code> is thrown when inappropriate. + </li> +<li> Only the GLS regressions require the covariance matrix, so in the OLS regression it is ignored and can be safely + inputted as <code>null</code>.</li> +</ul> +</p> +<p> + Here are some examples. + <dl><dt>OLS regression</dt> +<br /> +</br><dd>Instantiate an OLS regression object and load dataset + <div class="source"><pre> +MultipleLinearRegression regression = new OLSMultipleLinearRegression(); +double[] y = new double[]{11.0, 12.0, 13.0, 14.0, 15.0, 16.0}; +double[] x = new double[6][]; +x[0] = new double[]{1.0, 0, 0, 0, 0, 0}; +x[1] = new double[]{1.0, 2.0, 0, 0, 0, 0}; +x[2] = new double[]{1.0, 0, 3.0, 0, 0, 0}; +x[3] = new double[]{1.0, 0, 0, 4.0, 0, 0}; +x[4] = new double[]{1.0, 0, 0, 0, 5.0, 0}; +x[5] = new double[]{1.0, 0, 0, 0, 0, 6.0}; +regression.addData(y, x, null); // we don't need covariance + </pre> +</div> +</dd> +<dd>Estimate of regression values honours the <code>MultipleLinearRegression</code> interface: + <div class="source"><pre> +double[] beta = regression.estimateRegressionParameters(); + +double[] residuals = regression.estimateResiduals(); + +double[][] parametersVariance = regression.estimateRegressionParametersVariance(); + +double regressandVariance = regression.estimateRegressandVariance(); + </pre> +</div> +</dd> +<dt>GLS regression</dt> +<br /> +</br><dd>Instantiate an GLS regression object and load dataset + <div class="source"><pre> +MultipleLinearRegression regression = new GLSMultipleLinearRegression(); +double[] y = new double[]{11.0, 12.0, 13.0, 14.0, 15.0, 16.0}; +double[] x = new double[6][]; +x[0] = new double[]{1.0, 0, 0, 0, 0, 0}; +x[1] = new double[]{1.0, 2.0, 0, 0, 0, 0}; +x[2] = new double[]{1.0, 0, 3.0, 0, 0, 0}; +x[3] = new double[]{1.0, 0, 0, 4.0, 0, 0}; +x[4] = new double[]{1.0, 0, 0, 0, 5.0, 0}; +x[5] = new double[]{1.0, 0, 0, 0, 0, 6.0}; +double[][] omega = new double[6][]; +omega[0] = new double[]{1.1, 0, 0, 0, 0, 0}; +omega[1] = new double[]{0, 2.2, 0, 0, 0, 0}; +omega[2] = new double[]{0, 0, 3.3, 0, 0, 0}; +omega[3] = new double[]{0, 0, 0, 4.4, 0, 0}; +omega[4] = new double[]{0, 0, 0, 0, 5.5, 0}; +omega[5] = new double[]{0, 0, 0, 0, 0, 6.6}; +regression.addData(y, x, omega); // we do need covariance + </pre> +</div> +</dd> +<dd>Estimate of regression values honours the same <code>MultipleLinearRegression</code> interface as + the OLS regression. + </dd> +</dl> +</p> +</div> +<div class="section"><h3><a name="a1.6_Rank_transformations"></a>1.6 Rank transformations</h3> +<p> + Some statistical algorithms require that input data be replaced by ranks. + The <a href="../apidocs/org/apache/commons/math/stat/ranking/package-summary.html"> + org.apache.commons.math.stat.ranking</a> package provides rank transformation. + <a href="../apidocs/org/apache/commons/math/stat/ranking/RankingAlgorithm.html"> + RankingAlgorithm</a> defines the interface for ranking. + <a href="../apidocs/org/apache/commons/math/stat/ranking/NaturalRanking.html"> + NaturalRanking</a> provides an implementation that has two configuration options. + <ul><li><a href="../apidocs/org/apache/commons/math/stat/ranking/TiesStrategy.html"> + Ties strategy</a> deterimines how ties in the source data are handled by the ranking</li> +<li><a href="../apidocs/org/apache/commons/math/stat/ranking/NaNStrategy.html"> + NaN strategy</a> determines how NaN values in the source data are handled.</li> +</ul> +</p> +<p> + Examples: + <div class="source"><pre> +NaturalRanking ranking = new NaturalRanking(NaNStrategy.MINIMAL, +TiesStrategy.MAXIMUM); +double[] data = { 20, 17, 30, 42.3, 17, 50, + Double.NaN, Double.NEGATIVE_INFINITY, 17 }; +double[] ranks = ranking.rank(exampleData); + </pre> +</div> + + results in <code>ranks</code> containing <code>{6, 5, 7, 8, 5, 9, 2, 2, 5}.</code><div class="source"><pre> +new NaturalRanking(NaNStrategy.REMOVED,TiesStrategy.SEQUENTIAL).rank(exampleData); + </pre> +</div> + + returns <code>{5, 2, 6, 7, 3, 8, 1, 4}.</code></p> +<p> + The default <code>NaNStrategy</code> is NaNStrategy.MAXIMAL. This makes <code>NaN</code> + values larger than any other value (including <code>Double.POSITIVE_INFINITY</code>). The + default <code>TiesStrategy</code> is <code>TiesStrategy.AVERAGE,</code> which assigns tied + values the average of the ranks applicable to the sequence of ties. See the + <a href="../apidocs/org/apache/commons/math/stat/ranking/NaturalRanking.html"> + NaturalRanking</a> for more examples and <a href="../apidocs/org/apache/commons/math/stat/ranking/TiesStrategy.html"> + TiesStrategy</a> and <a href="../apidocs/org/apache/commons/math/stat/ranking/NaNStrategy.html">NaNStrategy</a> + for details on these configuration options. + </p> +</div> +<div class="section"><h3><a name="a1.7_Covariance_and_correlation"></a>1.7 Covariance and correlation</h3> +<p> + The <a href="../apidocs/org/apache/commons/math/stat/correlation/package-summary.html"> + org.apache.commons.math.stat.correlation</a> package computes covariances + and correlations for pairs of arrays or columns of a matrix. + <a href="../apidocs/org/apache/commons/math/stat/correlation/Covariance.html"> + Covariance</a> computes covariances, + <a href="../apidocs/org/apache/commons/math/stat/correlation/PearsonsCorrelation.html"> + PearsonsCorrelation</a> provides Pearson's Product-Moment correlation coefficients and + <a href="../apidocs/org/apache/commons/math/stat/correlation/SpearmansCorrelation.html"> + SpearmansCorrelation</a> computes Spearman's rank correlation. + </p> +<p><strong>Implementation Notes</strong><ul><li> + Unbiased covariances are given by the formula <br /> +</br><code>cov(X, Y) = sum [(x<sub>i</sub> - E(X))(y<sub>i</sub> - E(Y))] / (n - 1)</code> + where <code>E(X)</code> is the mean of <code>X</code> and <code>E(Y)</code> + is the mean of the <code>Y</code> values. Non-bias-corrected estimates use + <code>n</code> in place of <code>n - 1.</code> Whether or not covariances are + bias-corrected is determined by the optional parameter, "biasCorrected," which + defaults to <code>true.</code></li> +<li><a href="../apidocs/org/apache/commons/math/stat/correlation/PearsonsCorrelation.html"> + PearsonsCorrelation</a> computes correlations defined by the formula <br /> +</br><code>cor(X, Y) = sum[(x<sub>i</sub> - E(X))(y<sub>i</sub> - E(Y))] / [(n - 1)s(X)s(Y)]</code><br /> + + where <code>E(X)</code> and <code>E(Y)</code> are means of <code>X</code> and <code>Y</code> + and <code>s(X)</code>, <code>s(Y)</code> are standard deviations. + </li> +<li><a href="../apidocs/org/apache/commons/math/stat/correlation/SpearmansCorrelation.html"> + SpearmansCorrelation</a> applies a rank transformation to the input data and computes Pearson's + correlation on the ranked data. The ranking algorithm is configurable. By default, + <a href="../apidocs/org/apache/commons/math/stat/ranking/NaturalRanking.html"> + NaturalRanking</a> with default strategies for handling ties and NaN values is used. + </li> +</ul> +</p> +<p><strong>Examples:</strong><dl><dt><strong>Covariance of 2 arrays</strong></dt> +<br /> +</br><dd>To compute the unbiased covariance between 2 double arrays, + <code>x</code> and <code>y</code>, use: + <div class="source"><pre> +new Covariance().covariance(x, y) + </pre> +</div> + + For non-bias-corrected covariances, use + <div class="source"><pre> +covariance(x, y, false) + </pre> +</div> +</dd> +<br /> +</br><dt><strong>Covariance matrix</strong></dt> +<br /> +</br><dd> A covariance matrix over the columns of a source matrix <code>data</code> + can be computed using + <div class="source"><pre> +new Covariance().computeCovarianceMatrix(data) + </pre> +</div> + + The i-jth entry of the returned matrix is the unbiased covariance of the ith and jth + columns of <code>data.</code> As above, to get non-bias-corrected covariances, + use + <div class="source"><pre> +computeCovarianceMatrix(data, false) + </pre> +</div> +</dd> +<br /> +</br><dt><strong>Pearson's correlation of 2 arrays</strong></dt> +<br /> +</br><dd>To compute the Pearson's product-moment correlation between two double arrays + <code>x</code> and <code>y</code>, use: + <div class="source"><pre> +new PearsonsCorrelation().correlation(x, y) + </pre> +</div> +</dd> +<br /> +</br><dt><strong>Pearson's correlation matrix</strong></dt> +<br /> +</br><dd> A (Pearson's) correlation matrix over the columns of a source matrix <code>data</code> + can be computed using + <div class="source"><pre> +new PearsonsCorrelation().computeCorrelationMatrix(data) + </pre> +</div> + + The i-jth entry of the returned matrix is the Pearson's product-moment correlation between the + ith and jth columns of <code>data.</code></dd> +<br /> +</br><dt><strong>Pearson's correlation significance and standard errors</strong></dt> +<br /> +</br><dd> To compute standard errors and/or significances of correlation coefficients + associated with Pearson's correlation coefficients, start by creating a + <code>PearsonsCorrelation</code> instance + <div class="source"><pre> +PearsonsCorrelation correlation = new PearsonsCorrelation(data); + </pre> +</div> + + where <code>data</code> is either a rectangular array or a <code>RealMatrix.</code> + Then the matrix of standard errors is + <div class="source"><pre> +correlation.getCorrelationStandardErrors(); + </pre> +</div> + + The formula used to compute the standard error is <br /> +<code>SE<sub>r</sub> = ((1 - r<sup>2</sup>) / (n - 2))<sup>1/2</sup></code><br /> + + where <code>r</code> is the estimated correlation coefficient and + <code>n</code> is the number of observations in the source dataset.<br /> +<br /> +<strong>p-values</strong> for the (2-sided) null hypotheses that elements of + a correlation matrix are zero populate the RealMatrix returned by + <div class="source"><pre> +correlation.getCorrelationPValues() + </pre> +</div> +<code>getCorrelationPValues().getEntry(i,j)</code> is the + probability that a random variable distributed as <code>t<sub>n-2</sub></code> takes + a value with absolute value greater than or equal to <br /> +</br><code>|r<sub>ij</sub>|((n - 2) / (1 - r<sub>ij</sub><sup>2</sup>))<sup>1/2</sup></code>, + where <code>r<sub>ij</sub></code> is the estimated correlation between the ith and jth + columns of the source array or RealMatrix. This is sometimes referred to as the + <i>significance</i> of the coefficient.<br /> +<br /> + + For example, if <code>data</code> is a RealMatrix with 2 columns and 10 rows, then + <div class="source"><pre> +new PearsonsCorrelation(data).getCorrelationPValues().getEntry(0,1) + </pre> +</div> + + is the significance of the Pearson's correlation coefficient between the two columns + of <code>data</code>. If this value is less than .01, we can say that the correlation + between the two columns of data is significant at the 99% level. + </dd> +<br /> +</br><dt><strong>Spearman's rank correlation coefficient</strong></dt> +<br /> +</br><dd>To compute the Spearman's rank-moment correlation between two double arrays + <code>x</code> and <code>y</code>: + <div class="source"><pre> +new SpearmansCorrelation().correlation(x, y) + </pre> +</div> + + This is equivalent to + <div class="source"><pre> +RankingAlgorithm ranking = new NaturalRanking(); +new PearsonsCorrelation().correlation(ranking.rank(x), ranking.rank(y)) + </pre> +</div> +</dd> +<br /> +</br></dl> +</p> +</div> +<div class="section"><h3><a name="a1.8_Statistical_tests"></a>1.8 Statistical tests</h3> +<p> + The interfaces and implementations in the + <a href="../apidocs/org/apache/commons/math/stat/inference/"> + org.apache.commons.math.stat.inference</a> package provide + <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc22.htm" class="externalLink"> + Student's t</a>, + <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda35f.htm" class="externalLink"> + Chi-Square</a> and + <a href="http://www.itl.nist.gov/div898/handbook/prc/section4/prc43.htm" class="externalLink"> + One-Way ANOVA</a> test statistics as well as + <a href="http://www.cas.lancs.ac.uk/glossary_v1.1/hyptest.html#pvalue" class="externalLink"> + p-values</a> associated with <code>t-</code>, + <code>Chi-Square</code> and <code>One-Way ANOVA</code> tests. The + interfaces are + <a href="../apidocs/org/apache/commons/math/stat/inference/TTest.html"> + TTest</a>, + <a href="../apidocs/org/apache/commons/math/stat/inference/ChiSquareTest.html"> + ChiSquareTest</a>, and + <a href="../apidocs/org/apache/commons/math/stat/inference/OneWayAnova.html"> + OneWayAnova</a> with provided implementations + <a href="../apidocs/org/apache/commons/math/stat/inference/TTestImpl.html"> + TTestImpl</a>, + <a href="../apidocs/org/apache/commons/math/stat/inference/ChiSquareTestImpl.html"> + ChiSquareTestImpl</a> and + <a href="../apidocs/org/apache/commons/math/stat/inference/OneWayAnovaImpl.html"> + OneWayAnovaImpl</a>, respectively. + The + <a href="../apidocs/org/apache/commons/math/stat/inference/TestUtils.html"> + TestUtils</a> class provides static methods to get test instances or + to compute test statistics directly. The examples below all use the + static methods in <code>TestUtils</code> to execute tests. To get + test object instances, either use e.g., + <code>TestUtils.getTTest()</code> or use the implementation constructors + directly, e.g., + <code>new TTestImpl()</code>. + </p> +<p><strong>Implementation Notes</strong><ul><li>Both one- and two-sample t-tests are supported. Two sample tests + can be either paired or unpaired and the unpaired two-sample tests can + be conducted under the assumption of equal subpopulation variances or + without this assumption. When equal variances is assumed, a pooled + variance estimate is used to compute the t-statistic and the degrees + of freedom used in the t-test equals the sum of the sample sizes minus 2. + When equal variances is not assumed, the t-statistic uses both sample + variances and the + <a href="http://www.itl.nist.gov/div898/handbook/prc/section3/gifs/nu3.gif" class="externalLink"> + Welch-Satterwaite approximation</a> is used to compute the degrees + of freedom. Methods to return t-statistics and p-values are provided in each + case, as well as boolean-valued methods to perform fixed significance + level tests. The names of methods or methods that assume equal + subpopulation variances always start with "homoscedastic." Test or + test-statistic methods that just start with "t" do not assume equal + variances. See the examples below and the API documentation for + more details.</li> +<li>The validity of the p-values returned by the t-test depends on the + assumptions of the parametric t-test procedure, as discussed + <a href="http://www.basic.nwu.edu/statguidefiles/ttest_unpaired_ass_viol.html" class="externalLink"> + here</a></li> +<li>p-values returned by t-, chi-square and Anova tests are exact, based + on numerical approximations to the t-, chi-square and F distributions in the + <code>distributions</code> package. </li> +<li>p-values returned by t-tests are for two-sided tests and the boolean-valued + methods supporting fixed significance level tests assume that the hypotheses + are two-sided. One sided tests can be performed by dividing returned p-values + (resp. critical values) by 2.</li> +<li>Degrees of freedom for chi-square tests are integral values, based on the + number of observed or expected counts (number of observed counts - 1) + for the goodness-of-fit tests and (number of columns -1) * (number of rows - 1) + for independence tests.</li> +</ul> +</p> +<p><strong>Examples:</strong><dl><dt><strong>One-sample <code>t</code> tests</strong></dt> +<br /> +</br><dd>To compare the mean of a double[] array to a fixed value: + <div class="source"><pre> +double[] observed = {1d, 2d, 3d}; +double mu = 2.5d; +System.out.println(TestUtils.t(mu, observed)); + </pre> +</div> + + The code above will display the t-statisitic associated with a one-sample + t-test comparing the mean of the <code>observed</code> values against + <code>mu.</code></dd> +<dd>To compare the mean of a dataset described by a + <a href="../apidocs/org/apache/commons/math/stat/descriptive/StatisticalSummary.html"> + org.apache.commons.math.stat.descriptive.StatisticalSummary</a> to a fixed value: + <div class="source"><pre> +double[] observed ={1d, 2d, 3d}; +double mu = 2.5d; +SummaryStatistics sampleStats = new SummaryStatistics(); +for (int i = 0; i < observed.length; i++) { + sampleStats.addValue(observed[i]); +} +System.out.println(TestUtils.t(mu, observed)); +</pre> +</div> +</dd> +<dd>To compute the p-value associated with the null hypothesis that the mean + of a set of values equals a point estimate, against the two-sided alternative that + the mean is different from the target value: + <div class="source"><pre> +double[] observed = {1d, 2d, 3d}; +double mu = 2.5d; +System.out.println(TestUtils.tTest(mu, observed)); + </pre> +</div> + + The snippet above will display the p-value associated with the null + hypothesis that the mean of the population from which the + <code>observed</code> values are drawn equals <code>mu.</code></dd> +<dd>To perform the test using a fixed significance level, use: + <div class="source"><pre> +TestUtils.tTest(mu, observed, alpha); + </pre> +</div> + + where <code>0 < alpha < 0.5</code> is the significance level of + the test. The boolean value returned will be <code>true</code> iff the + null hypothesis can be rejected with confidence <code>1 - alpha</code>. + To test, for example at the 95% level of confidence, use + <code>alpha = 0.05</code></dd> +<br /> +</br><dt><strong>Two-Sample t-tests</strong></dt> +<br /> +</br><dd><strong>Example 1:</strong> Paired test evaluating + the null hypothesis that the mean difference between corresponding + (paired) elements of the <code>double[]</code> arrays + <code>sample1</code> and <code>sample2</code> is zero. + + To compute the t-statistic: + <div class="source"><pre> +TestUtils.pairedT(sample1, sample2); + </pre> +</div> +<p> + To compute the p-value: + <div class="source"><pre> +TestUtils.pairedTTest(sample1, sample2); + </pre> +</div> +</p> +<p> + To perform a fixed significance level test with alpha = .05: + <div class="source"><pre> +TestUtils.pairedTTest(sample1, sample2, .05); + </pre> +</div> +</p> + + The last example will return <code>true</code> iff the p-value + returned by <code>TestUtils.pairedTTest(sample1, sample2)</code> + is less than <code>.05</code></dd> +<dd><strong>Example 2: </strong> unpaired, two-sided, two-sample t-test using + <code>StatisticalSummary</code> instances, without assuming that + subpopulation variances are equal. + + First create the <code>StatisticalSummary</code> instances. Both + <code>DescriptiveStatistics</code> and <code>SummaryStatistics</code> + implement this interface. Assume that <code>summary1</code> and + <code>summary2</code> are <code>SummaryStatistics</code> instances, + each of which has had at least 2 values added to the (virtual) dataset that + it describes. The sample sizes do not have to be the same -- all that is required + is that both samples have at least 2 elements. + <p><strong>Note:</strong> The <code>SummaryStatistics</code> class does + not store the dataset that it describes in memory, but it does compute all + statistics necessary to perform t-tests, so this method can be used to + conduct t-tests with very large samples. One-sample tests can also be + performed this way. + (See <a href="#1.2 Descriptive statistics">Descriptive statistics</a> for details + on the <code>SummaryStatistics</code> class.) + </p> +<p> + To compute the t-statistic: + <div class="source"><pre> +TestUtils.t(summary1, summary2); + </pre> +</div> +</p> +<p> + To compute the p-value: + <div class="source"><pre> +TestUtils.tTest(sample1, sample2); + </pre> +</div> +</p> +<p> + To perform a fixed significance level test with alpha = .05: + <div class="source"><pre> +TestUtils.tTest(sample1, sample2, .05); + </pre> +</div> +</p> +<p> + In each case above, the test does not assume that the subpopulation + variances are equal. To perform the tests under this assumption, + replace "t" at the beginning of the method name with "homoscedasticT" + </p> +</dd> +<br /> +</br><dt><strong>Chi-square tests</strong></dt> +<br /> +</br><dd>To compute a chi-square statistic measuring the agreement between a + <code>long[]</code> array of observed counts and a <code>double[]</code> + array of expected counts, use: + <div class="source"><pre> +long[] observed = {10, 9, 11}; +double[] expected = {10.1, 9.8, 10.3}; +System.out.println(TestUtils.chiSquare(expected, observed)); + </pre> +</div> + + the value displayed will be + <code>sum((expected[i] - observed[i])^2 / expected[i])</code></dd> +<dd> To get the p-value associated with the null hypothesis that + <code>observed</code> conforms to <code>expected</code> use: + <div class="source"><pre> +TestUtils.chiSquareTest(expected, observed); + </pre> +</div> +</dd> +<dd> To test the null hypothesis that <code>observed</code> conforms to + <code>expected</code> with <code>alpha</code> siginficance level + (equiv. <code>100 * (1-alpha)%</code> confidence) where <code> + 0 < alpha < 1 </code> use: + <div class="source"><pre> +TestUtils.chiSquareTest(expected, observed, alpha); + </pre> +</div> + + The boolean value returned will be <code>true</code> iff the null hypothesis + can be rejected with confidence <code>1 - alpha</code>. + </dd> +<dd>To compute a chi-square statistic statistic associated with a + <a href="http://www.itl.nist.gov/div898/handbook/prc/section4/prc45.htm" class="externalLink"> + chi-square test of independence</a> based on a two-dimensional (long[][]) + <code>counts</code> array viewed as a two-way table, use: + <div class="source"><pre> +TestUtils.chiSquareTest(counts); + </pre> +</div> + + The rows of the 2-way table are + <code>count[0], ... , count[count.length - 1]. </code><br /> +</br> + The chi-square statistic returned is + <code>sum((counts[i][j] - expected[i][j])^2/expected[i][j])</code> + where the sum is taken over all table entries and + <code>expected[i][j]</code> is the product of the row and column sums at + row <code>i</code>, column <code>j</code> divided by the total count. + </dd> +<dd>To compute the p-value associated with the null hypothesis that + the classifications represented by the counts in the columns of the input 2-way + table are independent of the rows, use: + <div class="source"><pre> + TestUtils.chiSquareTest(counts); + </pre> +</div> +</dd> +<dd>To perform a chi-square test of independence with <code>alpha</code> + siginficance level (equiv. <code>100 * (1-alpha)%</code> confidence) + where <code>0 < alpha < 1 </code> use: + <div class="source"><pre> +TestUtils.chiSquareTest(counts, alpha); + </pre> +</div> + + The boolean value returned will be <code>true</code> iff the null + hypothesis can be rejected with confidence <code>1 - alpha</code>. + </dd> +<br /> +</br><dt><strong>One-Way Anova tests</strong></dt> +<br /> +</br><dd>To conduct a One-Way Analysis of Variance (ANOVA) to evaluate the + null hypothesis that the means of a collection of univariate datasets + are the same, start by loading the datasets into a collection, e.g. + <div class="source"><pre> +double[] classA = + {93.0, 103.0, 95.0, 101.0, 91.0, 105.0, 96.0, 94.0, 101.0 }; +double[] classB = + {99.0, 92.0, 102.0, 100.0, 102.0, 89.0 }; +double[] classC = + {110.0, 115.0, 111.0, 117.0, 128.0, 117.0 }; +List classes = new ArrayList(); +classes.add(classA); +classes.add(classB); +classes.add(classC); + </pre> +</div> + + Then you can compute ANOVA F- or p-values associated with the + null hypothesis that the class means are all the same + using a <code>OneWayAnova</code> instance or <code>TestUtils</code> + methods: + <div class="source"><pre> +double fStatistic = TestUtils.oneWayAnovaFValue(classes); // F-value +double pValue = TestUtils.oneWayAnovaPValue(classes); // P-value + </pre> +</div> + + To test perform a One-Way Anova test with signficance level set at 0.01 + (so the test will, assuming assumptions are met, reject the null + hypothesis incorrectly only about one in 100 times), use + <div class="source"><pre> +TestUtils.oneWayAnovaTest(classes, 0.01); // returns a boolean + // true means reject null hypothesis + </pre> +</div> +</dd> +</dl> +</p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/transform.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,184 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Transform methods</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <a href="../userguide/utilities.html">Utilities</a> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <strong>Transform Methods</strong> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a10_Transform_methods"></a>10 Transform methods</h2> +<p> + This package provides a few transformers for signal analysis. All transformers + provide both direct and inverse transforms. + <ul><li><code>FastFourierTransformer</code> (produces <code>Complex</code> results)</li> +<li><code>FastCosineTransformer</code> (produces real results)</li> +<li><code>FastSineTransformer</code> (produces real results)</li> +<li><code>FastHadamardTransformer</code> (produces real results)</li> +</ul> +</p> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libs/commons-math-2.1/docs/userguide/utilities.html Tue Jan 04 10:00:53 2011 +0100 @@ -0,0 +1,329 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Math - The Commons Math User Guide - Utilites</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <span id="bannerLeft"> + + Commons Math User Guide + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xright"> + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>User Guide</h5> + <ul> + + <li class="none"> + <a href="../userguide/index.html">Contents</a> + </li> + + <li class="none"> + <a href="../userguide/overview.html">Overview</a> + </li> + + <li class="none"> + <a href="../userguide/stat.html">Statistics</a> + </li> + + <li class="none"> + <a href="../userguide/random.html">Data Generation</a> + </li> + + <li class="none"> + <a href="../userguide/linear.html">Linear Algebra</a> + </li> + + <li class="none"> + <a href="../userguide/analysis.html">Numerical Analysis</a> + </li> + + <li class="none"> + <a href="../userguide/special.html">Special Functions</a> + </li> + + <li class="none"> + <strong>Utilities</strong> + </li> + + <li class="none"> + <a href="../userguide/complex.html">Complex Numbers</a> + </li> + + <li class="none"> + <a href="../userguide/distribution.html">Distributions</a> + </li> + + <li class="none"> + <a href="../userguide/fraction.html">Fractions</a> + </li> + + <li class="none"> + <a href="../userguide/transform.html">Transform Methods</a> + </li> + + <li class="none"> + <a href="../userguide/geometry.html">3D Geometry</a> + </li> + + <li class="none"> + <a href="../userguide/optimization.html">Optimization</a> + </li> + + <li class="none"> + <a href="../userguide/ode.html">Ordinary Differential Equations</a> + </li> + + <li class="none"> + <a href="../userguide/genetics.html">Genetic Algorithms</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="a6_Utilities"></a>6 Utilities</h2> +<div class="section"><h3><a name="a6.1_Overview"></a>6.1 Overview</h3> +<p> + The <a href="../apidocs/org/apache/commons/math/util/package-summary.html"> + org.apache.commons.math.util</a> package collects a group of array utilities, + value transformers, and numerical routines used by implementation classes in + commons-math. + </p> +</div> +<div class="section"><h3><a name="a6.2_Double_array_utilities"></a>6.2 Double array utilities</h3> +<p> + To maintain statistics based on a "rolling" window of values, a resizable + array implementation was developed and is provided for reuse in the + <code>util</code> package. The core functionality provided is described in + the documentation for the interface, + <a href="../apidocs/org/apache/commons/math/util/DoubleArray.html"> + org.apache.commons.math.util.DoubleArray.</a> This interface adds one + method, <code>addElementRolling(double)</code> to basic list accessors. + The <code>addElementRolling</code> method adds an element + (the actual parameter) to the end of the list and removes the first element + in the list. + </p> +<p> + The <a href="../apidocs/org/apache/commons/math/util/ResizableDoubleArray.html"> + org.apache.commons.math.util.ResizableDoubleArray</a> class provides a + configurable, array-backed implementation of the <code>DoubleArray</code> + interface. When <code>addElementRolling</code> is invoked, the underlying + array is expanded if necessary, the new element is added to the end of the + array and the "usable window" of the array is moved forward, so that + the first element is effectively discarded, what was the second becomes the + first, and so on. To efficiently manage storage, two maintenance + operations need to be periodically performed -- orphaned elements at the + beginning of the array need to be reclaimed and space for new elements at + the end needs to be created. Both of these operations are handled + automatically, with frequency / effect driven by the configuration + properties <code>expansionMode</code>, <code>expansionFactor</code> and + <code>contractionCriteria.</code> See + <a href="../apidocs/org/apache/commons/math/util/ResizableDoubleArray.html"> + ResizableDoubleArray</a> + for details. + </p> +</div> +<div class="section"><h3><a name="a6.3_intdouble_hash_map"></a>6.3 int/double hash map</h3> +<p> + The <a href="../apidocs/org/apache/commons/math/util/OpenIntToDoubleHashMap.html"> + org.apache.commons.math.util.OpenIntToDoubleHashMap</a> class provides a specialized + hash map implementation for int/double. This implementation has a much smaller memory + overhead than standard <code>java.util.HashMap</code> class. It uses open addressing + and primitive arrays, which greatly reduces the number of intermediate objects and + improve data locality. + </p> +</div> +<div class="section"><h3><a name="a6.4_Continued_Fractions"></a>6.4 Continued Fractions</h3> +<p> + The <a href="../apidocs/org/apache/commons/math/util/ContinuedFraction.html"> + org.apache.commons.math.util.ContinuedFraction</a> class provides a generic + way to create and evaluate continued fractions. The easiest way to create a + continued fraction is to subclass <code>ContinuedFraction</code> and + override the <code>getA</code> and <code>getB</code> methods which return + the continued fraction terms. The precise definition of these terms is + explained in <a href="http://mathworld.wolfram.com/ContinuedFraction.html" class="externalLink"> + Continued Fraction, equation (1)</a> from MathWorld. + </p> +<p> + As an example, the constant Pi could be computed using the continued fraction + defined at <a href="http://functions.wolfram.com/Constants/Pi/10/0002/" class="externalLink"> + http://functions.wolfram.com/Constants/Pi/10/0002/</a>. The following + anonymous class provides the implementation: + <div class="source"><pre>ContinuedFraction c = new ContinuedFraction() { + public double getA(int n, double x) { + switch(n) { + case 0: return 3.0; + default: return 6.0; + } + } + + public double getB(int n, double x) { + double y = (2.0 * n) - 1.0; + return y * y; + } +}</pre> +</div> +</p> +<p> + Then, to evalute Pi, simply call any of the <code>evalute</code> methods + (Note, the point of evalution in this example is meaningless since Pi is a + constant). + </p> +<p> + For a more practical use of continued fractions, consider the exponential + function with the continued fraction definition of + <a href="http://functions.wolfram.com/ElementaryFunctions/Exp/10/" class="externalLink"> + http://functions.wolfram.com/ElementaryFunctions/Exp/10/</a>. The + following anonymous class provides its implementation: + <div class="source"><pre>ContinuedFraction c = new ContinuedFraction() { + public double getA(int n, double x) { + if (n % 2 == 0) { + switch(n) { + case 0: return 1.0; + default: return 2.0; + } + } else { + return n; + } + } + + public double getB(int n, double x) { + if (n % 2 == 0) { + return -x; + } else { + return x; + } + } +}</pre> +</div> +</p> +<p> + Then, to evalute <i>e</i><sup>x</sup> for any value x, simply call any of the + <code>evalute</code> methods. + </p> +</div> +<div class="section"><h3><a name="a6.5_binomial_coefficients_factorials_and_other_common_math_functions"></a>6.5 binomial coefficients, factorials and other common math functions</h3> +<p> + A collection of reusable math functions is provided in the + <a href="../apidocs/org/apache/commons/math/util/MathUtils.html">MathUtils</a> + utility class. MathUtils currently includes methods to compute the following: <ul><li> + Binomial coeffiecients -- "n choose k" available as an (exact) long value, + <code>binomialCoefficient(int, int)</code> for small n, k; as a double, + <code>binomialCoefficientDouble(int, int)</code> for larger values; and in + a "super-sized" version, <code>binomialCoefficientLog(int, int)</code> + that returns the natural logarithm of the value.</li> +<li> + Factorials -- like binomial coefficients, these are available as exact long + values, <code>factorial(int)</code>; doubles, + <code>factorialDouble(int)</code>; or logs, <code>factorialLog(int)</code>. </li> +<li> + Hyperbolic sine and cosine functions -- + <code>cosh(double), sinh(double)</code></li> +<li> + sign (+1 if argument > 0, 0 if x = 0, and -1 if x < 0) and + indicator (+1.0 if argument >= 0 and -1.0 if argument < 0) functions + for variables of all primitive numeric types.</li> +<li> + a hash function, <code>hash(double),</code> returning a long-valued + hash code for a double value. + </li> +<li> + Convience methods to round floating-point number to arbitrary precision. + </li> +<li> + Least common multiple and greatest common denominator functions. + </li> +</ul> +</p> +</div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2003-2010 + + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>