You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by er...@apache.org on 2018/09/03 22:33:14 UTC
[1/5] commons-numbers git commit: NUMBERS-70: Delete files describing
"Commons Math" (userguide).
Repository: commons-numbers
Updated Branches:
refs/heads/master fff24948c -> b36e21d9a
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/stat.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/stat.xml b/src/site/xdoc/userguide/stat.xml
deleted file mode 100644
index 0b0870c..0000000
--- a/src/site/xdoc/userguide/stat.xml
+++ /dev/null
@@ -1,1246 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="stat.html">
- <properties>
- <title>The Commons Math User Guide - Statistics</title>
- </properties>
- <body>
- <section name="1 Statistics">
- <subsection name="1.1 Overview">
- <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/>
- <a href="#a1.3_Frequency_distributions">Frequency distributions</a><br/>
- <a href="#a1.4_Simple_regression">Simple Regression</a><br/>
- <a href="#a1.5_Multiple_linear_regression">Multiple Regression</a><br/>
- <a href="#a1.6_Rank_transformations">Rank transformations</a><br/>
- <a href="#a1.7_Covariance_and_correlation">Covariance and correlation</a><br/>
- <a href="#a1.8_Statistical_tests">Statistical Tests</a><br/>
- </p>
- </subsection>
- <subsection name="1.2 Descriptive statistics">
- <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/math4/stat/descriptive/UnivariateStatistic.html">
- 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/math4/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/math4/stat/descriptive/AbstractUnivariateStatistic.html">
- AbstractUnivariateStatistic</a> and
- <a href="../apidocs/org/apache/commons/math4/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/math4/stat/descriptive/DescriptiveStatistics.html">
- DescriptiveStatistics</a> and
- <a href="../apidocs/org/apache/commons/math4/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>
- <tr><th>Aggregate</th><th>Statistics Included</th><th>Values stored?</th>
- <th>"Rolling" capability?</th></tr><tr><td>
- <a href="../apidocs/org/apache/commons/math4/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><td>
- <a href="../apidocs/org/apache/commons/math4/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/math4/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/math4/stat/descriptive/SynchronizedDescriptiveStatistics.html">
- SynchronizedDescriptiveStatistics</a> and
- <a href="../apidocs/org/apache/commons/math4/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/math4/stat/descriptive/SynchronizedMultiVariateSummaryStatistics.html">
- SynchronizedMultivariateSummaryStatistics</a> provides thread-safe
- <code>MultivariateSummaryStatistics.</code>
- </p>
- <p>
- There is also a utility class,
- <a href="../apidocs/org/apache/commons/math4/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/>
- <dd>Using the <code>DescriptiveStatistics</code> aggregate
- (values are stored in memory):
- <source>
-// 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.getPercentile(50);
- </source>
- </dd>
- <dd>Using the <code>SummaryStatistics</code> aggregate (values are
- <strong>not</strong> stored in memory):
- <source>
-// 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
- </source>
- </dd>
- <dd>Using the <code>StatUtils</code> utility class:
- <source>
-// Compute statistics directly from the array
-// assume values is a double[] array
-double mean = StatUtils.mean(values);
-double std = FastMath.sqrt(StatUtils.variance(values));
-double median = StatUtils.percentile(values, 50);
-
-// Compute the mean of the first three values in the array
-mean = StatUtils.mean(values, 0, 3);
- </source>
- </dd>
- <dt>Maintain a "rolling mean" of the most recent 100 values from
- an input stream</dt>
- <br/>
- <dd>Use a <code>DescriptiveStatistics</code> instance with
- window size set to 100
- <source>
-// 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();
- </source>
- </dd>
- <dt>Compute statistics in a thread-safe manner</dt>
- <br/>
- <dd>Use a <code>SynchronizedDescriptiveStatistics</code> instance
- <source>
-// Create a SynchronizedDescriptiveStatistics instance and
-// use as any other DescriptiveStatistics instance
-DescriptiveStatistics stats = new SynchronizedDescriptiveStatistics();
- </source>
- </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/math4/stat/descriptive/AggregateSummaryStatistics.html#createContributingStatistics()">
- AggregateSummaryStatistics.createContributingStatistics()</a>:
- <source>
-// 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();
- </source>
- 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/math4/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.
- <source>
-// 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();
- </source>
- </dd>
- </dl>
- </p>
- </subsection>
- <subsection name="1.3 Frequency distributions">
- <p>
- <a href="../apidocs/org/apache/commons/math4/stat/Frequency.html">
- 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 overridden 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/>
- <dd>Mixing integers, longs, Integers and Longs:
- <source>
- 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
- </source>
- </dd>
- <dt>Count string frequencies</dt>
- <br/>
- <dd>Using case-sensitive comparison, alpha sort order (natural comparator):
- <source>
-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
- </source>
- </dd>
- <dd>Using case-insensitive comparator:
- <source>
-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
- </source>
- </dd>
- </dl>
- </p>
- </subsection>
- <subsection name="1.4 Simple regression">
- <p>
- <a href="../apidocs/org/apache/commons/math4/stat/regression/SimpleRegression.html">
- 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>
- or
- </p>
- <p>
- <code> y = 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 required 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>
- <li> The intercept term may be suppressed by passing <code>false</code> to the
- <a href="../apidocs/org/apache/commons/math4/stat/regression/SimpleRegression.html#SimpleRegression(boolean)">
- SimpleRegression(boolean)</a> constructor. When the <code>hasIntercept</code>
- property is false, the model is estimated without a constant term and
- <code>getIntercept()</code> returns <code>0</code>.</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">
- 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>
- <dd>Instantiate a regression instance and add data points
- <source>
-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.
- </source>
- </dd>
- <dd>Compute some statistics based on observations added so far
- <source>
-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
- </source>
- </dd>
- <dd>Use the regression model to predict the y value for a new x value
- <source>
-System.out.println(regression.predict(1.5d)
-// displays predicted y value for x = 1.5
- </source>
- More data points can be added and subsequent getXxx calls will incorporate
- additional data in statistics.
- </dd>
- <br/>
- <dt>Estimate a model from a double[][] array of data points</dt>
- <dd>Instantiate a regression object and load dataset
- <source>
-double[][] data = { { 1, 3 }, {2, 5 }, {3, 7 }, {4, 14 }, {5, 11 }};
-SimpleRegression regression = new SimpleRegression();
-regression.addData(data);
- </source>
- </dd>
- <dd>Estimate regression model based on data
- <source>
-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
- </source>
- More data points -- even another double[][] array -- can be added and subsequent
- getXxx calls will incorporate additional data in statistics.
- </dd>
-<br/>
- <dt>Estimate a model from a double[][] array of data points, <em>excluding</em> the intercept</dt>
- <dd>Instantiate a regression object and load dataset
- <source>
-double[][] data = { { 1, 3 }, {2, 5 }, {3, 7 }, {4, 14 }, {5, 11 }};
-SimpleRegression regression = new SimpleRegression(false);
-//the argument, false, tells the class not to include a constant
-regression.addData(data);
- </source>
- </dd>
- <dd>Estimate regression model based on data
- <source>
-System.out.println(regression.getIntercept());
-// displays intercept of regression line, since we have constrained the constant, 0.0 is returned
-
-System.out.println(regression.getSlope());
-// displays slope of regression line
-
-System.out.println(regression.getSlopeStdErr());
-// displays slope standard error
-
-System.out.println(regression.getInterceptStdErr() );
-// will return Double.NaN, since we constrained the parameter to zero
- </source>
- Caution must be exercised when interpreting the slope when no constant is being estimated. The slope
- may be biased.
- </dd>
-
- </dl>
- </p>
- </subsection>
- <subsection name="1.5 Multiple linear regression">
- <p>
- <a href="../apidocs/org/apache/commons/math4/stat/regression/OLSMultipleLinearRegression.html">
- OLSMultipleLinearRegression</a> and
- <a href="../apidocs/org/apache/commons/math4/stat/regression/GLSMultipleLinearRegression.html">
- GLSMultipleLinearRegression</a> provide least squares regression to fit the linear model:
- </p>
- <p>
- <code> Y=X*b+u </code>
- </p>
- <p>
- where Y is an n-vector <b>regressand</b>, X is a [n,k] matrix whose k columns are called
- <b>regressors</b>, b is k-vector of <b>regression parameters</b> and u is an n-vector
- of <b>error terms</b> or <b>residuals</b>.
- </p>
- <p>
- <a href="../apidocs/org/apache/commons/math4/stat/regression/OLSMultipleLinearRegression.html">
- OLSMultipleLinearRegression</a> provides Ordinary Least Squares Regression, and
- <a href="../apidocs/org/apache/commons/math4/stat/regression/GLSMultipleLinearRegression.html">
- GLSMultipleLinearRegression</a> implements Generalized Least Squares. See the javadoc for these
- classes for details on the algorithms and formulas used.
- </p>
- <p>
- Data for OLS models can be loaded in a single double[] array, consisting of concatenated rows of data, each containing
- the regressand (Y) value, followed by regressor values; or using a double[][] array with rows corresponding to
- observations. GLS models also require a double[][] array representing the covariance matrix of the error terms. See
- <a href="../apidocs/org/apache/commons/math4/stat/regression/AbstractMultipleLinearRegression.html#newSampleData(double[], int, int)">
- AbstractMultipleLinearRegression#newSampleData(double[],int,int)</a>,
- <a href="../apidocs/org/apache/commons/math4/stat/regression/OLSMultipleLinearRegression.html#newSampleData(double[], double[][])">
- OLSMultipleLinearRegression#newSampleData(double[], double[][])</a> and
- <a href="../apidocs/org/apache/commons/math4/stat/regression/GLSMultipleLinearRegression.html#newSampleData(double[], double[][], double[][])">
- GLSMultipleLinearRegression#newSampleData(double[],double[][],double[][])</a> for details.
- </p>
- <p>
- <strong>Usage Notes</strong>: <ul>
- <li> Data are validated when invoking any of the newSample, newX, newY or newCovariance methods and
- <code>IllegalArgumentException</code> is thrown when input data arrays do not have matching dimensions
- or do not contain sufficient data to estimate the model.
- </li>
- <li> By default, regression models are estimated with intercept terms. In the notation above, this implies that the
- X matrix contains an initial row identically equal to 1. X data supplied to the newX or newSample methods should not
- include this column - the data loading methods will create it automatically. To estimate a model without an intercept
- term, set the <code>noIntercept</code> property to <code>true.</code></li>
- </ul>
- </p>
- <p>
- Here are some examples.
- <dl>
- <dt>OLS regression</dt>
- <br/>
- <dd>Instantiate an OLS regression object and load a dataset:
- <source>
-OLSMultipleLinearRegression 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[]{0, 0, 0, 0, 0};
-x[1] = new double[]{2.0, 0, 0, 0, 0};
-x[2] = new double[]{0, 3.0, 0, 0, 0};
-x[3] = new double[]{0, 0, 4.0, 0, 0};
-x[4] = new double[]{0, 0, 0, 5.0, 0};
-x[5] = new double[]{0, 0, 0, 0, 6.0};
-regression.newSampleData(y, x);
- </source>
- </dd>
- <dd>Get regression parameters and diagnostics:
- <source>
-double[] beta = regression.estimateRegressionParameters();
-
-double[] residuals = regression.estimateResiduals();
-
-double[][] parametersVariance = regression.estimateRegressionParametersVariance();
-
-double regressandVariance = regression.estimateRegressandVariance();
-
-double rSquared = regression.calculateRSquared();
-
-double sigma = regression.estimateRegressionStandardError();
- </source>
- </dd>
- <dt>GLS regression</dt>
- <br/>
- <dd>Instantiate a GLS regression object and load a dataset:
- <source>
-GLSMultipleLinearRegression 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[]{0, 0, 0, 0, 0};
-x[1] = new double[]{2.0, 0, 0, 0, 0};
-x[2] = new double[]{0, 3.0, 0, 0, 0};
-x[3] = new double[]{0, 0, 4.0, 0, 0};
-x[4] = new double[]{0, 0, 0, 5.0, 0};
-x[5] = new double[]{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.newSampleData(y, x, omega);
- </source>
- </dd>
- </dl>
- </p>
- </subsection>
- <subsection name="1.6 Rank transformations">
- <p>
- Some statistical algorithms require that input data be replaced by ranks.
- The <a href="../apidocs/org/apache/commons/math4/stat/ranking/package-summary.html">
- org.apache.commons.complex.stat.ranking</a> package provides rank transformation.
- <a href="../apidocs/org/apache/commons/math4/stat/ranking/RankingAlgorithm.html">
- RankingAlgorithm</a> defines the interface for ranking.
- <a href="../apidocs/org/apache/commons/math4/stat/ranking/NaturalRanking.html">
- NaturalRanking</a> provides an implementation that has two configuration options.
- <ul>
- <li><a href="../apidocs/org/apache/commons/math4/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/math4/stat/ranking/NaNStrategy.html">
- NaN strategy</a> determines how NaN values in the source data are handled.</li>
- </ul>
- </p>
- <p>
- Examples:
- <source>
-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);
- </source>
- results in <code>ranks</code> containing <code>{6, 5, 7, 8, 5, 9, 2, 2, 5}.</code>
- <source>
-new NaturalRanking(NaNStrategy.REMOVED,TiesStrategy.SEQUENTIAL).rank(exampleData);
- </source>
- 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/math4/stat/ranking/NaturalRanking.html">
- NaturalRanking</a> for more examples and <a href="../apidocs/org/apache/commons/math4/stat/ranking/TiesStrategy.html">
- TiesStrategy</a> and <a href="../apidocs/org/apache/commons/math4/stat/ranking/NaNStrategy.html">NaNStrategy</a>
- for details on these configuration options.
- </p>
- </subsection>
- <subsection name="1.7 Covariance and correlation">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/stat/correlation/package-summary.html">
- org.apache.commons.complex.stat.correlation</a> package computes covariances
- and correlations for pairs of arrays or columns of a matrix.
- <a href="../apidocs/org/apache/commons/math4/stat/correlation/Covariance.html">
- Covariance</a> computes covariances,
- <a href="../apidocs/org/apache/commons/math4/stat/correlation/PearsonsCorrelation.html">
- PearsonsCorrelation</a> provides Pearson's Product-Moment correlation coefficients,
- <a href="../apidocs/org/apache/commons/math4/stat/correlation/SpearmansCorrelation.html">
- SpearmansCorrelation</a> computes Spearman's rank correlation and
- <a href="../apidocs/org/apache/commons/math4/stat/correlation/KendallsCorrelation.html">
- KendallsCorrelation</a> computes Kendall's tau rank correlation.
- </p>
- <p>
- <strong>Implementation Notes</strong>
- <ul>
- <li>
- Unbiased covariances are given by the formula <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/math4/stat/correlation/PearsonsCorrelation.html">
- PearsonsCorrelation</a> computes correlations defined by the formula <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/math4/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/math4/stat/ranking/NaturalRanking.html">
- NaturalRanking</a> with default strategies for handling ties and NaN values is used.
- </li>
- <li>
- <a href="../apidocs/org/apache/commons/math4/stat/correlation/KendallsCorrelation.html">
- KendallsCorrelation</a> computes the association between two measured quantities. A tau test
- is a non-parametric hypothesis test for statistical dependence based on the tau coefficient.
- </li>
- </ul>
- </p>
- <p>
- <strong>Examples:</strong>
- <dl>
- <dt><strong>Covariance of 2 arrays</strong></dt>
- <br/>
- <dd>To compute the unbiased covariance between 2 double arrays,
- <code>x</code> and <code>y</code>, use:
- <source>
-new Covariance().covariance(x, y)
- </source>
- For non-bias-corrected covariances, use
- <source>
-covariance(x, y, false)
- </source>
- </dd>
- <br/>
- <dt><strong>Covariance matrix</strong></dt>
- <br/>
- <dd> A covariance matrix over the columns of a source matrix <code>data</code>
- can be computed using
- <source>
-new Covariance().computeCovarianceMatrix(data)
- </source>
- 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
- <source>
-computeCovarianceMatrix(data, false)
- </source>
- </dd>
- <br/>
- <dt><strong>Pearson's correlation of 2 arrays</strong></dt>
- <br/>
- <dd>To compute the Pearson's product-moment correlation between two double arrays
- <code>x</code> and <code>y</code>, use:
- <source>
-new PearsonsCorrelation().correlation(x, y)
- </source>
- </dd>
- <br/>
- <dt><strong>Pearson's correlation matrix</strong></dt>
- <br/>
- <dd> A (Pearson's) correlation matrix over the columns of a source matrix <code>data</code>
- can be computed using
- <source>
-new PearsonsCorrelation().computeCorrelationMatrix(data)
- </source>
- 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/>
- <dt><strong>Pearson's correlation significance and standard errors</strong></dt>
- <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
- <source>
-PearsonsCorrelation correlation = new PearsonsCorrelation(data);
- </source>
- where <code>data</code> is either a rectangular array or a <code>RealMatrix.</code>
- Then the matrix of standard errors is
- <source>
-correlation.getCorrelationStandardErrors();
- </source>
- 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
- <source>
-correlation.getCorrelationPValues()
- </source>
- <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/>
- <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
- <source>
-new PearsonsCorrelation(data).getCorrelationPValues().getEntry(0,1)
- </source>
- 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/>
- <dt><strong>Spearman's rank correlation coefficient</strong></dt>
- <br/>
- <dd>To compute the Spearman's rank-moment correlation between two double arrays
- <code>x</code> and <code>y</code>:
- <source>
-new SpearmansCorrelation().correlation(x, y)
- </source>
- This is equivalent to
- <source>
-RankingAlgorithm ranking = new NaturalRanking();
-new PearsonsCorrelation().correlation(ranking.rank(x), ranking.rank(y))
- </source>
- </dd>
- <br/>
- <dt><strong>Kendalls's tau rank correlation coefficient</strong></dt>
- <br/>
- <dd>To compute the Kendall's tau rank correlation between two double arrays
- <code>x</code> and <code>y</code>:
- <source>
-new KendallsCorrelation().correlation(x, y)
- </source>
- </dd>
- </dl>
- </p>
- </subsection>
- <subsection name="1.8 Statistical tests">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/stat/inference/">
- org.apache.commons.complex.stat.inference</a> package provides implementations for
- <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc22.htm">
- Student's t</a>,
- <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda35f.htm">
- Chi-Square</a>,
- <a href="http://en.wikipedia.org/wiki/G-test">G Test</a>,
- <a href="http://www.itl.nist.gov/div898/handbook/prc/section4/prc43.htm">
- One-Way ANOVA</a>,
- <a href="http://www.itl.nist.gov/div898/handbook/prc/section3/prc35.htm">
- Mann-Whitney U</a>,
- <a href="http://en.wikipedia.org/wiki/Wilcoxon_signed-rank_test">
- Wilcoxon signed rank</a> and
- <a href="http://en.wikipedia.org/wiki/Binomial_test">
- Binomial</a> test statistics as well as
- <a href="http://www.cas.lancs.ac.uk/glossary_v1.1/hyptest.html#pvalue">
- p-values</a> associated with <code>t-</code>,
- <code>Chi-Square</code>, <code>G</code>, <code>One-Way ANOVA</code>, <code>Mann-Whitney U</code>
- <code>Wilcoxon signed rank</code>, and <code>Kolmogorov-Smirnov</code> tests.
- The respective test classes are
- <a href="../apidocs/org/apache/commons/math4/stat/inference/TTest.html">
- TTest</a>,
- <a href="../apidocs/org/apache/commons/math4/stat/inference/ChiSquareTest.html">
- ChiSquareTest</a>,
- <a href="../apidocs/org/apache/commons/math4/stat/inference/GTest.html">
- GTest</a>,
- <a href="../apidocs/org/apache/commons/math4/stat/inference/OneWayAnova.html">
- OneWayAnova</a>,
- <a href="../apidocs/org/apache/commons/math4/stat/inference/MannWhitneyUTest.html">
- MannWhitneyUTest</a>,
- <a href="../apidocs/org/apache/commons/math4/stat/inference/WilcoxonSignedRankTest.html">
- WilcoxonSignedRankTest</a>,
- <a href="../apidocs/org/apache/commons/math4/stat/inference/BinomialTest.html">
- BinomialTest</a> and
- <a href="../apidocs/org/apache/commons/math4/stat/inference/KolmogorovSmirnovTest.html">
- KolmogorovSmirnovTest</a>.
- The <a href="../apidocs/org/apache/commons/math4/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 TTest()</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">
- 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">
- 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>The G test implementation provides two p-values:
- <code>gTest(expected, observed)</code>, which is the tail probability beyond
- <code>g(expected, observed)</code> in the ChiSquare distribution with degrees
- of freedom one less than the common length of input arrays and
- <code>gTestIntrinsic(expected, observed)</code> which is the same tail
- probability computed using a ChiSquare distribution with one less degeree
- of freedom. </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 G- and chi-square tests are integral values, based on the
- number of observed or expected counts (number of observed counts - 1).</li>
- <li> The KolmogorovSmirnov test uses a statistic based on the maximum deviation of
- the empirical distribution of sample data points from the distribution expected
- under the null hypothesis. Specifically, what is computed is
- \(D_n=\sup_x |F_n(x)-F(x)|\), where \(F\) is the expected distribution and
- \(F_n\) is the empirical distribution of the \(n\) sample data points. Both
- one-sample tests against a <code>RealDistribution</code> and two-sample tests
- (comparing two empirical distributions) are supported. For one-sample tests,
- the distribution of \(D_n\) is estimated using the method in
- <a href="http://www.jstatsoft.org/v08/i18/">Evaluating Kolmogorov's Distribution</a> by
- George Marsaglia, Wai Wan Tsang, and Jingbo Wang, with quick decisions in some cases
- for extreme values using the method described in
- <a href="http://www.jstatsoft.org/v39/i11/"> Computing the Two-Sided Kolmogorov-Smirnov
- Distribution</a> by Richard Simard and Pierre L'Ecuyer. In the 2-sample case, estimation
- by default depends on the number of data points. For small samples, the distribution
- is computed exactly and for large samples a numerical approximation of the Kolmogorov
- distribution is used. Methods to perform each type of p-value estimation are also exposed
- directly. See the class javadoc for details.</li>
- </ul>
- </p>
- <p>
- <strong>Examples:</strong>
- <dl>
- <dt><strong>One-sample <code>t</code> tests</strong></dt>
- <br/>
- <dd>To compare the mean of a double[] array to a fixed value:
- <source>
-double[] observed = {1d, 2d, 3d};
-double mu = 2.5d;
-System.out.println(TestUtils.t(mu, observed));
- </source>
- The code above will display the t-statistic 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/math4/stat/descriptive/StatisticalSummary.html">
- StatisticalSummary</a> to a fixed value:
- <source>
-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));
-</source>
- </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:
- <source>
-double[] observed = {1d, 2d, 3d};
-double mu = 2.5d;
-System.out.println(TestUtils.tTest(mu, observed));
- </source>
- 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:
- <source>
-TestUtils.tTest(mu, observed, alpha);
- </source>
- 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/>
- <dt><strong>Two-Sample t-tests</strong></dt>
- <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.
- <p>
- To compute the t-statistic:
- <source>
-TestUtils.pairedT(sample1, sample2);
- </source>
- </p>
- <p>
- To compute the p-value:
- <source>
-TestUtils.pairedTTest(sample1, sample2);
- </source>
- </p>
- <p>
- To perform a fixed significance level test with alpha = .05:
- <source>
-TestUtils.pairedTTest(sample1, sample2, .05);
- </source>
- </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.
- <p>
- 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>
- <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:
- <source>
-TestUtils.t(summary1, summary2);
- </source>
- </p>
- <p>
- To compute the p-value:
- <source>
-TestUtils.tTest(sample1, sample2);
- </source>
- </p>
- <p>
- To perform a fixed significance level test with alpha = .05:
- <source>
-TestUtils.tTest(sample1, sample2, .05);
- </source>
- </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/>
- <dt><strong>Chi-square tests</strong></dt>
- <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:
- <source>
-long[] observed = {10, 9, 11};
-double[] expected = {10.1, 9.8, 10.3};
-System.out.println(TestUtils.chiSquare(expected, observed));
- </source>
- 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:
- <source>
-TestUtils.chiSquareTest(expected, observed);
- </source>
- </dd>
- <dd> To test the null hypothesis that <code>observed</code> conforms to
- <code>expected</code> with <code>alpha</code> significance level
- (equiv. <code>100 * (1-alpha)%</code> confidence) where <code>
- 0 < alpha < 1 </code> use:
- <source>
-TestUtils.chiSquareTest(expected, observed, alpha);
- </source>
- 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">
- chi-square test of independence</a> based on a two-dimensional (long[][])
- <code>counts</code> array viewed as a two-way table, use:
- <source>
-TestUtils.chiSquareTest(counts);
- </source>
- The rows of the 2-way table are
- <code>count[0], ... , count[count.length - 1]. </code><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:
- <source>
- TestUtils.chiSquareTest(counts);
- </source>
- </dd>
- <dd>To perform a chi-square test of independence with <code>alpha</code>
- significance level (equiv. <code>100 * (1-alpha)%</code> confidence)
- where <code>0 < alpha < 1 </code> use:
- <source>
-TestUtils.chiSquareTest(counts, alpha);
- </source>
- The boolean value returned will be <code>true</code> iff the null
- hypothesis can be rejected with confidence <code>1 - alpha</code>.
- </dd>
- <br/>
- <dt><strong>G tests</strong></dt>
- <br/>
- <dd>G tests are an alternative to chi-square tests that are recommended
- when observed counts are small and / or incidence probabilities for
- some cells are small. See Ted Dunning's paper,
- <a href="http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.14.5962">
- Accurate Methods for the Statistics of Surprise and Coincidence</a> for
- background and an empirical analysis showing now chi-square
- statistics can be misleading in the presence of low incidence probabilities.
- This paper also derives the formulas used in computing G statistics and the
- root log likelihood ratio provided by the <code>GTest</code> class.
- </dd>
- <dd>To compute a G-test statistic measuring the agreement between a
- <code>long[]</code> array of observed counts and a <code>double[]</code>
- array of expected counts, use:
- <source>
-double[] expected = new double[]{0.54d, 0.40d, 0.05d, 0.01d};
-long[] observed = new long[]{70, 79, 3, 4};
-System.out.println(TestUtils.g(expected, observed));
- </source>
- the value displayed will be
- <code>2 * sum(observed[i]) * log(observed[i]/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:
- <source>
-TestUtils.gTest(expected, observed);
- </source>
- </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:
- <source>
-TestUtils.gTest(expected, observed, alpha);
- </source>
- 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 evaluate the hypothesis that two sets of counts come from the
- same underlying distribution, use long[] arrays for the counts and
- <code>gDataSetsComparison</code> for the test statistic
- <source>
-long[] obs1 = new long[]{268, 199, 42};
-long[] obs2 = new long[]{807, 759, 184};
-System.out.println(TestUtils.gDataSetsComparison(obs1, obs2)); // G statistic
-System.out.println(TestUtils.gTestDataSetsComparison(obs1, obs2)); // p-value
- </source>
- </dd>
- <dd>For 2 x 2 designs, the <code>rootLogLikelihoodRatio</code> method
- computes the
- <a href="http://tdunning.blogspot.com/2008/03/surprise-and-coincidence.html">
- signed root log likelihood ratio.</a> For example, suppose that for two events
- A and B, the observed count of AB (both occurring) is 5, not A and B (B without A)
- is 1995, A not B is 0; and neither A nor B is 10000. Then
- <source>
-new GTest().rootLogLikelihoodRatio(5, 1995, 0, 100000);
- </source>
- returns the root log likelihood associated with the null hypothesis that A
- and B are independent.
- </dd>
- <br/>
- <dt><strong>One-Way ANOVA tests</strong></dt>
- <br/>
- <dd>
- <source>
-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);
- </source>
- 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:
- <source>
-double fStatistic = TestUtils.oneWayAnovaFValue(classes); // F-value
-double pValue = TestUtils.oneWayAnovaPValue(classes); // P-value
- </source>
- To test perform a One-Way ANOVA test with significance 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
- <source>
-TestUtils.oneWayAnovaTest(classes, 0.01); // returns a boolean
- // true means reject null hypothesis
- </source>
- </dd>
- <br/>
- <dt><strong>Kolmogorov-Smirnov tests</strong></dt>
- <br/>
- <dd>Given a double[] array <code>data</code> of values, to evaluate the
- null hypothesis that the values are drawn from a unit normal distribution
- <source>
-final NormalDistribution unitNormal = new NormalDistribution(0d, 1d);
-TestUtils.kolmogorovSmirnovTest(unitNormal, sample, false)
- </source>
- returns the p-value and
- <source>
-TestUtils.kolmogorovSmirnovStatistic(unitNormal, sample)
- </source>
- returns the D-statistic.
- <br/>
- If <code>y</code> is a double array, to evaluate the null hypothesis that
- <code>x</code> and <code>y</code> are drawn from the same underlying distribution,
- use
- <source>
-TestUtils.kolmogorovSmirnovStatistic(x, y)
- </source>
- to compute the D-statistic and
- <source>
-TestUtils.kolmogorovSmirnovTest(x, y)
- </source>
- for the p-value associated with the null hypothesis that <code>x</code> and
- <code>y</code> come from the same distribution. By default, here and above strict
- inequality is used in the null hypothesis - i.e., we evaluate \(H_0 : D_{n,m} > d \).
- To make the inequality above non-strict, add <code>false</code> as an actual parameter
- above. For large samples, this parameter makes no difference.
- <br/>
- To force exact computation of the p-value (overriding the selection of estimation
- method), first compute the d-statistic and then use the <code>exactP</code> method
- <source>
-final double d = TestUtils.kolmogorovSmirnovStatistic(x, y);
-TestUtils.exactP(d, x.length, y.length, false)
- </source>
- assuming that the non-strict form of the null hypothesis is desired. Note, however,
- that exact computation for large samples takes a long time.
- </dd>
- </dl>
- </p>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/transform.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/transform.xml b/src/site/xdoc/userguide/transform.xml
deleted file mode 100644
index 56cdec0..0000000
--- a/src/site/xdoc/userguide/transform.xml
+++ /dev/null
@@ -1,45 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="transform.html">
-
- <properties>
- <title>The Commons Math User Guide - Transform methods</title>
- </properties>
-
- <body>
- <section name="10 Transform methods">
- <p>
- This package provides a few transformers for signal analysis. All transformers
- provide both direct and inverse transforms.
- <ul>
- <li><a href="../apidocs/org/apache/commons/math4/transform/FastFourierTransformer.html">
- FastFourierTransformer</a> (produces <code>Complex</code> results)</li>
- <li><a href="../apidocs/org/apache/commons/math4/transform/FastCosineTransformer.html">
- FastCosineTransformer</a> (produces real results)</li>
- <li><a href="../apidocs/org/apache/commons/math4/transform/FastSineTransformer.html">
- FastSineTransformer</a> (produces real results)</li>
- <li><a href="../apidocs/org/apache/commons/math4/transform/FastHadamardTransformer.html">
- FastHadamardTransformer</a> (produces real results)</li>
- </ul>
- </p>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/utilities.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/utilities.xml b/src/site/xdoc/userguide/utilities.xml
deleted file mode 100644
index c6e2a11..0000000
--- a/src/site/xdoc/userguide/utilities.xml
+++ /dev/null
@@ -1,246 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="utilities.html">
-
-<properties>
- <title>The Commons Math User Guide - Utilites</title>
-</properties>
-
-<body>
-
-<section name="6 Utilities">
-
-<subsection name="6.1 Overview" href="overview">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/util/package-summary.html">
- org.apache.commons.complex.util</a> package collects a group of array utilities,
- value transformers, and numerical routines used by implementation classes in
- commons-math.
- </p>
-</subsection>
-
-<subsection name="6.2 Double array utilities" href="arrays">
- <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/math4/util/DoubleArray.html">
- 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/math4/util/ResizableDoubleArray.html">
- 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/math4/util/ResizableDoubleArray.html">
- ResizableDoubleArray</a>
- for details.
- </p>
-</subsection>
-
-<subsection name="6.3 int/double hash map" href="int_double_hash_map">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/util/OpenIntToDoubleHashMap.html">
- 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>
-</subsection>
-
-<subsection name="6.4 Continued Fractions" href="continued_fractions">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/util/ContinuedFraction.html">
- 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">
- Continued Fraction, equation (1)</a> from MathWorld.
- </p>
- <p>
- As an example, the constant Pi can be computed using a <a href="http://functions.wolfram.com/Constants/Pi/10/0002/">continued fraction</a>. The following anonymous class
- provides the implementation:
- <source>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;
- }
-}</source>
- </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 <a href="http://functions.wolfram.com/ElementaryFunctions/Exp/10/">exponential function</a>.
- The following anonymous class provides its implementation:
- <source>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;
- }
- }
-}</source>
- </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>
-</subsection>
-
-<subsection name="6.5 Binomial coefficients, factorials, Stirling numbers and other common math functions" href="binomial_coefficients_factorials_and_other_common_math_functions">
- <p>
- A collection of reusable math functions is provided in the
- <a href="../apidocs/org/apache/commons/math4/util/ArithmeticUtils.html">ArithmeticUtils</a>
- utility class. ArithmeticUtils currently includes methods to compute the following: <ul>
- <li>
- Binomial coefficients -- "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>
- Stirling numbers of the second kind -- S(n,k) as an exact long value
- <code>stirlingS2(int, int)</code> for small n, k.</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>
- Least common multiple and greatest common denominator functions.
- </li>
- </ul>
- </p>
-</subsection>
-
-<subsection name="6.6 Fast mathematical functions" href="fast_math">
- <p>
- Apache Commons Math provides a faster, more accurate, portable alternative
- to the regular <code>Math</code> and <code>StrictMath</code>classes for large
- scale computation.
- </p>
- <p>
- FastMath is a drop-in replacement for both Math and StrictMath. This
- means that for any method in Math (say <code>Math.sin(x)</code> or
- <code>Math.cbrt(y)</code>), user can directly change the class and use the
- methods as is (using <code>FastMath.sin(x)</code> or <code>FastMath.cbrt(y)</code>
- in the previous example).
- </p>
- <p>
- FastMath speed is achieved by relying heavily on optimizing compilers to
- native code present in many JVM todays and use of large tables. Precomputed
- literal arrays are provided in this class to speed up load time. These
- precomputed tables are used in the default configuration, to improve speed
- even at first use of the class. If users prefer to compute the tables
- automatically at load time, they can change a compile-time constant. This will
- increase class load time at first use, but this overhead will occur only once
- per run, regardless of the number of subsequent calls to computation methods.
- Note that FastMath is extensively used inside Apache Commons Math, so by
- calling some algorithms, the one-shot overhead when the constant is set to
- false will occur regardless of the end-user calling FastMath methods directly
- or not. Performance figures for a specific JVM and hardware can be evaluated by
- running the FastMathTestPerformance tests in the test directory of the source
- distribution.
- </p>
- <p>
- FastMath accuracy should be mostly independent of the JVM as it relies only
- on IEEE-754 basic operations and on embedded tables. Almost all operations
- are accurate to about 0.5 ulp throughout the domain range. This statement, of
- course is only a rough global observed behavior, it is <em>not</em> a guarantee
- for <em>every</em> double numbers input (see William Kahan's <a
- href="http://en.wikipedia.org/wiki/Rounding#The_table-maker.27s_dilemma">Table
- Maker's Dilemma</a>).
- </p>
- <p>
- FastMath additionally implements the following methods not found in Math/StrictMath:
- <ul>
- <li>asinh(double)</li>
- <li>acosh(double)</li>
- <li>atanh(double)</li>
- <li>pow(double,int)</li>
- </ul>
- The following methods are found in Math/StrictMath since 1.6 only, they are
- provided by FastMath even in 1.5 Java virtual machines
- <ul>
- <li>copySign(double, double)</li>
- <li>getExponent(double)</li>
- <li>nextAfter(double,double)</li>
- <li>nextUp(double)</li>
- <li>scalb(double, int)</li>
- <li>copySign(float, float)</li>
- <li>getExponent(float)</li>
- <li>nextAfter(float,double)</li>
- <li>nextUp(float)</li>
- <li>scalb(float, int)</li>
- </ul>
- </p>
-</subsection>
-
-<subsection name="6.7 Miscellaneous" href="miscellaneous">
- The <a href="../apidocs/org/apache/commons/math4/util/MultidimensionalCounter.html">
- MultidimensionalCounter</a> is a utility class that converts a set of indices
- (identifying points in a multidimensional space) to a single index (e.g. identifying
- a location in a one-dimensional array.
-</subsection>
-
-</section>
-
-</body>
-</document>
[4/5] commons-numbers git commit: NUMBERS-70: Delete files describing
"Commons Math" (userguide).
Posted by er...@apache.org.
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/fitting.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/fitting.xml b/src/site/xdoc/userguide/fitting.xml
deleted file mode 100644
index 6caace8..0000000
--- a/src/site/xdoc/userguide/fitting.xml
+++ /dev/null
@@ -1,144 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="fitting.html">
-
- <properties>
- <title>The Commons Math User Guide - Curve Fitting</title>
- </properties>
-
- <body>
- <section name="13 Curve Fitting">
- <subsection name="13.1 Overview" href="overview">
- <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 Σ(y<sub>i</sub> - f(x<sub>i</sub>))<sup>2</sup>. This is actually a
- least-squares problem.
- </p>
- <p>
- For all provided curve fitters, the operating principle is the same.
- Users must
- <ul>
- <li>
- create an instance of the fitter using the <code>create</code> factory method of the
- appropriate class,
- </li>
- <li>
- call the <a href="../apidocs/org/apache/commons/math4/fitting/AbstractCurveFitter">fit</a>
- with a <code>Collection</code> of <a href="../apidocs/org/apache/commons/math4/fitting/WeightedObservedPoint.html">
- observed data points</a> as argument, which will return an array with the parameters that
- best fit the given data points.
- </li>
- </ul>
-
- The list of observed data points to be passed to <code>fit</code> can be built by incrementally
- adding instances to an instance of <a href="../apidocs/org/apache/commons/math4/fitting/WeightedObservedPoints.html">WeightedObservedPoints</a>,
- and then retrieve the list of <code>WeightedObservedPoint</code> by calling the <code>toList</code>
- method on that container.
- A weight can be associated with each observed point; it allows to take into account uncertainty
- on some points when they come from noisy 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 (and this
- is the default when no weight is passed to the <code>add</code>.
- </p>
-
- <p>
- Some fitters require that initial values for the parameters are provided by the user,
- through the <code>withStartPoint</code> method, before attempting to perform the fit.
- When that's the case the fitter class usually defines a guessing procedure within a
- <code>ParameterGuesser</code> inner class, that attempts to provide appropriate initial
- values based on the user-supplied data.
- When initial values are required but are not provided, the <code>fit</code> method will
- internally call the guessing procedure.
- </p>
-
- </subsection>
-
- <subsection name="13.2 Implemented Functions" href="special">
-
- <p>
- Fitting of specific functions are provided through the following classes:
- <ul>
- <li>
- <a href="../apidocs/org/apache/commons/math4/fitting/PolynomialCurveFitter.html">
- PolynomialFitter</a> fits a
- <a href="../apidocs/org/apache/commons/math4/analysis/polynomials/PolynomialFunction.Parametric.html">
- polynomial</a> function.
- </li>
- <li>
- <a href="../apidocs/org/apache/commons/math4/fitting/HarmonicCurveFitter.html">
- HarmonicFitter</a> fits a
- <a href="../apidocs/org/apache/commons/math4/analysis/function/HarmonicOscillator.Parametric.html">
- harmonic</a> function.
- An instance of the inner class <a href="../apidocs/org/apache/commons/math4/fitting/HarmonicCurveFitter.ParameterGuesser.html">
- ParameterGuesser</a> can be used to retrieve initial values for the fitting procedure.
- </li>
- <li>
- <a href="../apidocs/org/apache/commons/math4/fitting/GaussianCurveFitter.html">
- GaussianFitter</a> fits a
- <a href="../apidocs/org/apache/commons/math4/analysis/function/Gaussian.Parametric.html">
- Gaussian</a> function.
- An instance of the inner class <a href="../apidocs/org/apache/commons/math4/fitting/GaussianCurveFitter.ParameterGuesser.html">
- ParameterGuesser</a> can be used to retrieve initial values for the fitting procedure.
- </li>
- </ul>
- </p>
-
- <p>
- The following example shows how to fit data with a polynomial function.
- </p>
-
- <source>// Collect data.
-final WeightedObservedPoints obs = new WeightedObservedPoints();
-obs.add(-1.00, 2.021170021833143);
-obs.add(-0.99, 2.221135431136975);
-obs.add(-0.98, 2.09985277659314);
-obs.add(-0.97, 2.0211192647627025);
-// ... Lots of lines omitted ...
-obs.addt(0.99, -2.4345814727089854);
-
-// Instantiate a third-degree polynomial fitter.
-final PolynomialCurveFitter fitter = PolynomialCurveFitter.create(3);
-
-// Retrieve fitted parameters (coefficients of the polynomial function).
-final double[] coeff = fitter.fit(obs.toList());
- </source>
-
- </subsection>
-
- <subsection name="13.3 General Case" href="general">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/fitting/AbstractCurveFitter.html">
- AbstractCurveFitter</a> class provides the basic functionality for implementing other
- curve fitting classes.
- Users must provide their own implementation of the curve template as a class that implements
- the <a href="../apidocs/org/apache/commons/math4/analysis/ParametricUnivariateFunction.html">
- ParametricUnivariateFunction</a> interface.
- </p>
- </subsection>
-
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/fraction.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/fraction.xml b/src/site/xdoc/userguide/fraction.xml
deleted file mode 100644
index 3f8ae51..0000000
--- a/src/site/xdoc/userguide/fraction.xml
+++ /dev/null
@@ -1,109 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="fraction.html">
- <properties>
- <title>The Commons Math User Guide - Fractions</title>
- </properties>
- <body>
- <section name="9 Fractions">
- <subsection name="9.1 Overview" href="overview">
- <p>
- The fraction packages provides a fraction number type as well as
- fraction number formatting.
- </p>
- </subsection>
- <subsection name="9.2 Fraction Numbers" href="fraction">
- <p>
- <a href="../apidocs/org/apache/commons/math4/fraction/Fraction.html">
- Fraction</a> and <a href="../apidocs/org/apache/commons/math4/fraction/BigFraction.html">
- 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:
- <source>Fraction f = new Fraction(1, 3); // 1 / 3
-Fraction g = new Fraction(0.25); // 1 / 4</source>
- </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>:
- <source>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</source>
- </p>
- <p>
- Like fraction construction, for each of the fraction functions, the resulting fraction is reduced to lowest terms.
- </p>
- </subsection>
- <subsection name="9.3 Fraction Formatting and Parsing" href="formatting">
- <p>
- <code>Fraction</code> instances can be converted to and from strings
- using the<a href="../apidocs/org/apache/commons/math4/fraction/FractionFormat.html">
- 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>):
- <source>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</source>
- </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:
- <source>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"</source>
- </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:
- <source>FractionFormat ff = new FractionFormat();
-Fraction f = ff.parse("-10 / 21");</source>
- </p>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/genetics.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/genetics.xml b/src/site/xdoc/userguide/genetics.xml
deleted file mode 100644
index 1455a8d..0000000
--- a/src/site/xdoc/userguide/genetics.xml
+++ /dev/null
@@ -1,134 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="genetics.html">
- <properties>
- <title>The Commons Math User Guide - Genetic Algorithms</title>
- </properties>
- <body>
- <section name="16 Genetic Algorithms">
- <subsection name="16.1 Overview" href="overview">
- <p>
- The genetics package provides a framework and implementations for
- genetic algorithms.
- </p>
- </subsection>
- <subsection name="16.2 GA Framework">
- <p>
- <a href="../apidocs/org/apache/commons/math4/genetics/GeneticAlgorithm.html">
- GeneticAlgorithm</a> provides an execution framework for Genetic Algorithms (GA).
- <a href="../apidocs/org/apache/commons/math4/genetics/Population.html">
- Populations,</a> consisting of <a href="../apidocs/org/apache/commons/math4/genetics/Chromosome.html">
- Chromosomes</a> are evolved by the <code>GeneticAlgorithm</code> until a
- <a href="../apidocs/org/apache/commons/math4/genetics/StoppingCondition.html">
- StoppingCondition</a> is reached. Evolution is determined by <a href="../apidocs/org/apache/commons/math4/genetics/SelectionPolicy.html">
- SelectionPolicy</a>, <a href="../apidocs/org/apache/commons/math4/genetics/MutationPolicy.html">
- MutationPolicy</a> and <a href="../apidocs/org/apache/commons/math4/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:
- <source>public Population evolve(Population initial, StoppingCondition condition) {
- Population current = initial;
- while (!condition.isSatisfied(current)) {
- current = nextGeneration(current);
- }
- return current;
-}
- </source>
- The <code>nextGeneration</code> method implements the following algorithm:
- <ol>
- <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/math4/genetics/GeneticAlgorithm.html#getCrossoverRate()">
- getCrossoverRate()</a>, apply configured <code>CrossoverPolicy</code> to parents</li>
- <li>With probability =
- <a href="../apidocs/org/apache/commons/math4/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>
- </subsection>
- <subsection name="16.3 Implementation">
- <p>
- Here is an example GA execution:
- <source>
-// 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();
- </source>
- The arguments to the <code>GeneticAlgorithm</code> constructor above are: <br/>
- <table>
- <tr><th>Parameter</th><th>value in example</th><th>meaning</th></tr>
- <tr><td>crossoverPolicy</td>
- <td><a href="../apidocs/org/apache/commons/math4/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><td>crossoverRate</td>
- <td>1</td>
- <td>Always apply crossover</td></tr>
- <tr><td>mutationPolicy</td>
- <td><a href="../apidocs/org/apache/commons/math4/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><td>mutationRate</td>
- <td>.1</td>
- <td>Apply mutation with probability 0.1 - that is, 10% of the time.</td></tr>
- <tr><td>selectionPolicy</td>
- <td><a href="../apidocs/org/apache/commons/math4/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/math4/genetics/StoppingCondition.html">StoppingCondition</a>
- is reached. In the example above, a
- <a href="../apidocs/org/apache/commons/math4/genetics/FixedGenerationCount.html">FixedGenerationCount</a>
- stopping condition is used, which means the algorithm proceeds through a fixed number of generations.
- </p>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/geometry.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/geometry.xml b/src/site/xdoc/userguide/geometry.xml
deleted file mode 100644
index fc6c635..0000000
--- a/src/site/xdoc/userguide/geometry.xml
+++ /dev/null
@@ -1,338 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="geometry.html">
-
- <properties>
- <title>The Commons Math User Guide - Geometry</title>
- </properties>
-
- <body>
- <section name="11 Geometry">
- <subsection name="11.1 Overview" href="overview">
- <p>
- The geometry package provides classes useful for many physical simulations
- in Euclidean spaces, like vectors and rotations in 3D, as well as on the
- sphere. It also provides a general implementation of Binary Space Partitioning
- Trees (BSP trees).
- </p>
- <p>
- All supported type of spaces (Euclidean 3D, Euclidean 2D, Euclidean 1D, 2-Sphere
- and 1-Sphere) provide dedicated classes that represent complex regions of the
- space as shown in the following table:
- </p>
- <p>
- <table border="1" align="center">
- <tr BGCOLOR="#CCCCFF"><td colspan="2"><font size="+1">Regions</font></td></tr>
- <tr BGCOLOR="#EEEEFF"><font size="+1"><td>Space</td><td>Region</td></font></tr>
- <tr><td>Euclidean 1D</td><td><a href="../apidocs/org/apache/commons/math4/geometry/euclidean/oned/IntervalsSet.html">IntervalsSet</a></td></tr>
- <tr><td>Euclidean 2D</td><td><a href="../apidocs/org/apache/commons/math4/geometry/euclidean/twod/PolygonsSet.html">PolygonsSet</a></td></tr>
- <tr><td>Euclidean 3D</td><td><a href="../apidocs/org/apache/commons/math4/geometry/euclidean/threed/PolyhedronsSet.html">PolyhedronsSet</a></td></tr>
- <tr><td>1-Sphere</td><td><a href="../apidocs/org/apache/commons/math4/geometry/spherical/oned/ArcsSet.html">ArcsSet</a></td></tr>
- <tr><td>2-Sphere</td><td><a href="../apidocs/org/apache/commons/math4/geometry/spherical/twod/SphericalPolygonsSet.html">SphericalPolygonsSet</a></td></tr>
- </table>
- </p>
- <p>
- All these regions share common features. Regions can be defined from several non-connected parts.
- As an example, one PolygonsSet instance in Euclidean 2D (i.e. the plane) can represent a region composed
- of several separated polygons separate from each other. They also support regions containing holes. As an example
- a SphericalPolygonsSet on the 2-Sphere can represent a land mass on the Earth with an interior sea, where points
- on this sea would not be considered to belong to the land mass. Of course more complex models can also be represented
- and it is possible to define for example one region composed of several continents, with interior sea containing
- separate islands, some of which having lakes, which may have smaller island ... In the infinite Euclidean spaces,
- regions can have infinite parts. for example in 1D (i.e. along a line), one can define an interval starting at
- abscissa 3 and extending up to infinity. This is also possible in 2D and 3D. For all spaces, regions without any
- boundaries are also possible so one can define the whole space or the empty region.
- </p>
- <p>
- The classical set operations are available in all cases: union, intersection, symmetric difference (exclusive or),
- difference, complement. There are also region predicates (point inside/outside/on boundary, emptiness,
- other region contained). Some geometric properties like size, or boundary size
- can be computed, as well as barycenters on the Euclidean space. Another important feature available for all these
- regions is the projection of a point to the closest region boundary (if there is a boundary). The projection provides
- both the projected point and the signed distance between the point and its projection, with the convention distance
- to boundary is considered negative if the point is inside the region, positive if the point is outside the region
- and of course 0 if the point is already on the boundary. This feature can be used for example as the value of a
- function in a root solver to determine when a moving point crosses the region boundary.
- </p>
- </subsection>
-
- <subsection name="11.2 Euclidean spaces" href="euclidean">
- <p>
- <a href="../apidocs/org/apache/commons/math4/geometry/euclidean/oned/Vector1D.html">
- Vector1D</a>, <a href="../apidocs/org/apache/commons/math4/geometry/euclidean/twod/Vector2D.html">
- Vector2D</a> and <a href="../apidocs/org/apache/commons/math4/geometry/euclidean/threed/Vector3D.html">
- Vector3D</a> provide simple vector types. One important feature is
- that instances of these classes are guaranteed
- to be immutable, this greatly simplifies modeling 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/math4/geometry/euclidean/oned/Vector1DFormat.html">
- Vector1DFormat</a>, <a href="../apidocs/org/apache/commons/math4/geometry/euclidean/twod/Vector2DFormat.html">
- Vector2DFormat</a> and <a href="../apidocs/org/apache/commons/math4/geometry/euclidean/threed/Vector3DFormat.html">
- Vector3DFormat</a> are specialized classes for formatting output or parsing
- input with text representation of vectors.
- </p>
- <p>
- <a href="../apidocs/org/apache/commons/math4/geometry/euclidean/threed/Rotation.html">
- 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 implicitly 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>
- <source>double[] angles = new Rotation(matrix, 1.0e-10).getAngles(RotationOrder.XYZ, RotationConvention.FRAME_TRANSFORM);</source>
- <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>
- In order to support naturally both views, the enumerate RotationConvention
- has been introduced in version 3.6. This enumerate can take two values:
- <code>VECTOR_OPERATOR</code> or <code>FRAME_TRANSFORM</code>. This
- enumerate must be passed as an argument to the few methods that depend
- on an interpretation of the semantics of the angle/axis. The value
- <code>VECTOR_OPERATOR</code> corresponds to rotations that are
- considered to move vectors within a fixed frame. The value
- <code>FRAME_TRANSFORM</code> corresponds to rotations that are
- considered to represent frame rotations, so fixed vectors coordinates
- change as their reference frame changes.
- </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>compose(Rotation, RotationConvention)</code> and
- <code>composeInverse(Rotation, RotationConvention)</code>. There are also
- shortcuts <code>applyTo(Rotation)</code> which is equivalent to
- <code>compose(Rotation, RotationConvention.VECTOR_OPERATOR)</code> and
- <code>applyInverseTo(Rotation)</code> which is equivalent to
- <code>composeInverse(Rotation, RotationConvention.VECTOR_OPERATOR)</code>.
- </p>
- </subsection>
- <subsection name="11.3 n-Sphere" href="sphere">
- <p>
- The Apache Commons Math library provides a few classes dealing with geometry
- on the 1-sphere (i.e. the one dimensional circle corresponding to the boundary of
- a two-dimensional disc) and the 2-sphere (i.e. the two dimensional sphere surface
- corresponding to the boundary of a three-dimensional ball). The main classes in
- this package correspond to the region explained above, i.e.
- <a href="../apidocs/org/apache/commons/math4/geometry/spherical/oned/ArcsSet.html">ArcsSet</a>
- and <a href="../apidocs/org/apache/commons/math4/geometry/spherical/twod/SphericalPolygonsSet.html">SphericalPolygonsSet</a>.
- </p>
- </subsection>
- <subsection name="11.4 Binary Space Partitioning" href="partitioning">
- <p>
- <a href="../apidocs/org/apache/commons/math4/geometry/partitioning/BSPTree.html">
- BSP trees</a> are an efficient way to represent space partitions and
- to associate attributes with each cell. Each node in a BSP tree
- represents a convex region which is partitioned in two convex
- sub-regions at each side of a cut hyperplane. The root tree
- contains the complete space.
- </p>
-
- <p>
- The main use of such partitions is to use a boolean attribute to
- define an inside/outside property, hence representing arbitrary
- polytopes (line segments in 1D, polygons in 2D and polyhedrons in
- 3D) and to operate on them. This is how the regions explained above in the Euclidean
- and Sphere spaces are implemented. The partitioning package provides the engine to do the
- computation, but not the dimension-specific implementations. The
- various interfaces in this package (hyperplane, sub-hyperplane, embedding,
- and even region) are therefore not considered to be reusable public
- interface, they are private interface. They may change and users are not expected to
- rely directly on them. What users can rely on is the BSP tree class itself, and the
- space-specific implementations of the interfaces (i.e. Plane in 3D as the implementation
- of hyperplane, or S2Point on the 2-Sphere as the implementation of Point).
- </p>
-
- <p>
- Another example of BST tree use would be to represent Voronoi tesselations, the
- attribute of each cell holding the defining point of the cell. This is not
- available yet.
- </p>
-
- <p>
- The application-defined attributes are shared among copied
- instances and propagated to split parts. These attributes are not
- used by the BSP-tree algorithms themselves, so the application can
- use them for any purpose. Since the tree visiting method holds
- internal and leaf nodes differently, it is possible to use
- different classes for internal nodes attributes and leaf nodes
- attributes. This should be used with care, though, because if the
- tree is modified in any way after attributes have been set, some
- internal nodes may become leaf nodes and some leaf nodes may become
- internal nodes.
- </p>
- </subsection>
- <subsection name="11.5 Regions">
- <p>
- The regions in all Euclidean and spherical spaces are based on BSP-tree using a <code>Boolean</code>
- attribute in the leaf cells representing the inside status of the corresponding cell
- (true for inside cells, false for outside cells). They all need a <code>tolerance</code> setting that
- is either provided at construction when the region is built from scratch or inherited from the input
- regions when a region is build by set operations applied to other regions. This setting is used when
- the region itself will be used later in another set operation or when points are tested against the
- region to compute inside/outside/on boundary status. This tolerance is the <em>thickness</em>
- of the hyperplane. Points closer than this value to a boundary hyperplane will be considered
- <em>on boundary</em>. There are no default values anymore for this setting (there was one when
- BSP-tree support was introduced, but it created more problems than it solved, so it has been intentionally
- removed). Setting this tolerance really depends on the expected values for the various coordinates. If for
- example the region is used to model a geological structure with a scale of a few thousand meters, the expected
- coordinates order of magnitude will be about 10<sup>3</sup> and the tolerance could be set to 10<sup>-7</sup>
- (i.e. 0.1 micrometer) or above. If very thin triangles or nearly parallel lines occur, it may be safer to use
- a larger value like 10<sup>-3</sup> for example. Of course if the BSP-tree is used to model a crystal at
- atomic level with coordinates of the order of magnitude about 10<sup>-9</sup> the tolerance should be
- drastically reduced (perhaps down to 10<sup>-20</sup> or so).
- </p>
- <p>
- The recommended way to build regions is to start from basic shapes built from their boundary representation
- and to use the set operations to combine these basic shapes into more complex shapes. The basic shapes
- that can be constructed from boundary representations must have a closed boundary and be in one part
- without holes. Regions in several non-connected parts or with holes must be built by building the parts
- beforehand and combining them. All regions (<code>IntervalsSet</code>, <code>PolygonsSet</code>,
- <code>PolyhedronsSet</code>, <code>ArcsSet</code>, <code>SphericalPolygonsSet</code>) provide a dedicated
- constructor using only the mandatory tolerance distance without any other parameters that always create
- the region covering the full space. The empty region case, can be built by building first the full space
- region and applying the <code>RegionFactory.getComplement()</code> method to it to get the corresponding
- empty region, it can also be built directly for a one-cell BSP-tree as explained below.
- </p>
- <p>
- Another way to build regions is to create directly the underlying BSP-tree. All regions (<code>IntervalsSet</code>,
- <code>PolygonsSet</code>, <code>PolyhedronsSet</code>, <code>ArcsSet</code>, <code>SphericalPolygonsSet</code>)
- provide a dedicated constructor that accepts a BSP-tree and a tolerance. This way to build regions should be
- reserved to dimple cases like the full space, the empty space of regions with only one or two cut hyperplances.
- It is not recommended in the general case and is considered expert use. The leaf nodes of the BSP-tree
- <em>must</em> have a <code>Boolean</code> attribute representing the inside status of the corresponding cell
- (true for inside cells, false for outside cells). In order to avoid building too many small objects, it is
- recommended to use the predefined constants <code>Boolean.TRUE</code> and <code>Boolean.FALSE</code>. Using
- this method, one way to build directly an empty region without complementing the full region is as follows
- (note the tolerance parameter which must be present even for the empty region):
- </p>
- <source>
-PolygonsSet empty = new PolygonsSet(new BSPTree<Euclidean2D>(false), tolerance);
- </source>
- <p>
- In the Euclidean 3D case, the <a href="../apidocs/org/apache/commons/math4/geometry/euclidean/threed/PolyhedronsSet.html">PolyhedronsSet</a>
- class has another specific constructor to build regions from vertices and facets. The signature of this
- constructor is:
- </p>
- <source>
-PolyhedronsSet(List<Vector3D> vertices, List<int[]> facets, double tolerance);
- </source>
- <p>
- The vertices list contains all the vertices of the polyhedrons, the facets list defines the facets,
- as an indirection in the vertices list. Each facet is a short integer array and each element in a
- facet array is the index of one vertex in the list. So in our cube example, the vertices list would
- contain 8 points corresponding to the cube vertices, the facets list would contain 6 facets (the sides
- of the cube) and each facet would contain 4 integers corresponding to the indices of the 4 vertices
- defining one side. Of course, each vertex would be referenced once in three different facets.
- </p>
- <p>
- Beware that despite some basic consistency checks are performed in the constructor, not everything
- is checked, so it remains under caller responsibility to ensure the vertices and facets are consistent
- and properly define a polyhedrons set. One particular trick is that when defining a facet, the vertices
- <em>must</em> be provided as walking the polygons boundary in <em>trigonometric</em> order (i.e.
- counterclockwise) as seen from the *external* side of the facet. The reason for this is that the walking
- order does define the orientation of the inside and outside parts, so walking the boundary on the wrong
- order would reverse the facet and the polyhedrons would not be the one you intended to define. Coming
- back to our cube example, a logical orientation of the facets would define the polyhedrons as the finite
- volume within the cube to be the inside and the infinite space surrounding the cube as the outside, but
- reversing all facets would also define a perfectly well behaved polyhedrons which would have the infinite
- space surrounding the cube as its inside and the finite volume within the cube as its outside!
- </p>
- <p>
- If one wants to further look at how it works, there is a test parser for PLY file formats in the unit tests
- section of the library and some basic ply files for a simple geometric shape (the N pentomino) in the test
- resources. This parser uses the constructor defined above as the PLY file format uses vertices and facets
- to represent 3D shapes.
- </p>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/index.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/index.xml b/src/site/xdoc/userguide/index.xml
index 81bdd22..a4e6d47 100644
--- a/src/site/xdoc/userguide/index.xml
+++ b/src/site/xdoc/userguide/index.xml
@@ -20,172 +20,17 @@
<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
<document url="index.html">
<properties>
- <title>The Commons Math User Guide - Table of Contents</title>
+ <title>The Commons Numbers User Guide - Table of Contents</title>
</properties>
<body>
<section name="Table of Contents" href="toc">
-
- <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_Error-handling">4.2 Error handling</a></li>
- <li><a href="analysis.html#a4.3_Root-finding">4.3 Root-finding</a></li>
- <li><a href="analysis.html#a4.4_Interpolation">4.4 Interpolation</a></li>
- <li><a href="analysis.html#a4.5_Integration">4.5 Integration</a></li>
- <li><a href="analysis.html#a4.6_Polynomials">4.6 Polynomials</a></li>
- <li><a href="analysis.html#a4.7_Differentiation">4.7 Differentiation</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_Stirling_numbers_and_other_common_math_functions">6.5 Binomial coefficients, factorials, Stirling numbers and other common math functions</a></li>
- <li><a href="utilities.html#a6.6_fast_math">6.6 Fast mathematical functions</a></li>
- <li><a href="utilities.html#a6.7_miscellaneous">6.7 Miscellaneous</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_Euclidean_spaces">11.2 Euclidean spaces</a></li>
- <li><a href="geometry.html#a11.3_n-Sphere">11.3 n-Sphere</a></li>
- <li><a href="geometry.html#a11.4_Binary_Space_Partitioning">11.4 Binary Space Partitioning</a></li>
- <li><a href="geometry.html#a11.5_Regions">11.5 Regions</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="optimization.html#a12.2_Univariate_Functions">12.2 Univariate Functions</a></li>
- <li><a href="optimization.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="optimization.html#a12.5_General_Case">12.5 General Case</a></li>
- </ul></li>
- <li><a href="fitting.html">13. Curve Fitting</a>
- <ul>
- <li><a href="fitting.html#a13.1_Overview">13.1 Overview</a></li>
- <li><a href="fitting.html#a13.2_Implemented_Functions">13.2 Implemented Functions</a></li>
- <li><a href="fitting.html#a13.3_General_Case">13.3 General Case</a></li>
- </ul>
- </li>
- <li><a href="leastsquares.html">14. Least Squares</a>
- <ul>
- <li><a href="fitting.html#a14.1_Overview">14.1 Overview</a></li>
- <li><a href="fitting.html#a14.2_LeastSquaresBuilder_and_LeastSquaresFactory">14.2 LeastSquaresBuilder and LeastSquaresFactory</a></li>
- <li><a href="fitting.html#a14.3_Model_Function">14.3 Model Function</a></li>
- <li><a href="fitting.html#a14.4_Parameters_Validation">14.4 Parameters Validation</a></li>
- <li><a href="fitting.html#a14.5_Tuning">14.5 Tuning</a></li>
- <li><a href="fitting.html#a14.6_Optimization_Engine">14.6 Optimization Engine</a></li>
- <li><a href="fitting.html#a14.7_Solving">14.7 Solving</a></li>
- <li><a href="fitting.html#a14.8_Example">14.8 Example</a></li>
- </ul>
- </li>
- <li><a href="ode.html">15. Ordinary Differential Equations Integration</a>
- <ul>
- <li><a href="ode.html#a15.1_Overview">15.1 Overview</a></li>
- <li><a href="ode.html#a15.2_Continuous_Output">15.2 Continuous Output</a></li>
- <li><a href="ode.html#a15.3_Discrete_Events_Handling">15.3 Discrete Events Handling</a></li>
- <li><a href="ode.html#a15.4_Available_Integrators">15.4 Available Integrators</a></li>
- <li><a href="ode.html#a15.5_Derivatives">15.5 Derivatives</a></li>
- </ul></li>
- <li><a href="genetics.html">16. Genetic Algorithms</a>
- <ul>
- <li><a href="genetics.html#a16.1_Overview">16.1 Overview</a></li>
- <li><a href="genetics.html#a16.2_GA_Framework">16.2 GA Framework</a></li>
- <li><a href="genetics.html#a16.3_Implementation">16.3 Implementation and Examples</a></li>
- </ul></li>
- <li><a href="filter.html">17. Filters</a>
- <ul>
- <li><a href="filter.html#a17.1_Overview">17.1 Overview</a></li>
- <li><a href="filter.html#a17.2_Kalman_Filter">17.2 Kalman Filter</a></li>
+ <ul>
+ <li>
+ <a href="core.html">1. Core</a>
+ </li>
</ul>
- </li>
- <li><a href="ml.html">18. Machine Learning</a>
- <ul>
- <li><a href="ml.html#overview">18.1 Overview</a></li>
- <li><a href="ml.html#clustering">18.2 Clustering algorithms and distance measures</a></li>
- <li><a href="ml.html#implementation">18.3 Implementation</a></li>
- </ul>
- </li>
- <li><a href="exceptions.html">19. Exceptions</a>
- <ul>
- <li><a href="exceptions.html#a19.1_Overview">19.1 Overview</a></li>
- <li><a href="exceptions.html#a19.2_Unchecked_Exceptions">19.2 Unchecked Exceptions</a></li>
- <li><a href="exceptions.html#a19.3_Hierarchies">19.3 Hierarchies</a></li>
- <li><a href="exceptions.html#a19.4_Features">19.4 Features</a></li>
- </ul>
- </li>
- </ul>
</section>
-
</body>
-
+
</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/leastsquares.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/leastsquares.xml b/src/site/xdoc/userguide/leastsquares.xml
deleted file mode 100644
index 8da9e78..0000000
--- a/src/site/xdoc/userguide/leastsquares.xml
+++ /dev/null
@@ -1,366 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="fitting.html">
-
- <properties>
- <title>The Commons Math User Guide - Least squares</title>
- </properties>
-
- <body>
- <section name="14 Least squares">
- <subsection name="14.1 Overview">
- <p>
- The least squares package fits a parametric model to a set of observed
- values by minimizing a cost function with a specific form.
- The fitting basically consists in finding the values
- for some parameters p<sub>k</sub> such that a cost function
- J = sum(w<sub>i</sub>(target<sub>i</sub> - model<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>
- Two engines devoted to least-squares problems are available. The first one is
- based on the <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/GaussNewtonOptimizer.html">
- Gauss-Newton</a> method. The second one is the <a
- href="../apidocs/org/apache/commons/math4/fitting/leastsquares/LevenbergMarquardtOptimizer.html">
- Levenberg-Marquardt</a> method.
- </p>
- </subsection>
-
- <subsection name="14.2 LeastSquaresBuilder and LeastSquaresFactory">
-
- <p>
- In order to solve a least-squares fitting problem, the user must provide the following elements:
- <ul>
- <li>a mean to evaluate all the components of the model for a given set of parameters:
- model<sub>i</sub> = f<sub>i</sub>(p<sub>1</sub>, p<sub>2</sub>, ... p<sub>k</sub>),
- this is code</li>
- <li>the target (or observed) components: target<sub>i</sub>, this is data</li>
- <li>the start values for all p<sub>k</sub> parameters: s<sub>k</sub>, this is data</li>
- <li>optionally a validator for the p<sub>k</sub> parameters, this is code</li>
- <li>optionally the weight for sample point i: w<sub>i</sub>, this is data and defaults to 1.0 if not provided</li>
- <li>a maximum number of iterations, this is data</li>
- <li>a maximum number of evaluations, this is data</li>
- <li>a convergence criterion, this is code</li>
- </ul>
- </p>
- <p>
- The elements of the list above can be provided as an implementation of the
- <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/LeastSquaresProblem.html">
- LeastSquaresProblem</a> interface. However, this is cumbersome to do directly, so some helper
- classes are available. The first helper is a mutable builder:
- <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/LeastSquaresBuilder.html">
- LeastSquaresBuilder</a>. The second helper is an utility factory:
- <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/LeastSquaresFactory.html">
- LeastSquaresFactory</a>.
- </p>
- <p>
- The builder class is better suited when setting the various elements of the least squares
- problem is done progressively in different places in the user code. In this case, the user
- would create first an empty builder andconfigure it progressively by calling its methods
- (<code>start</code>, <code>target</code>, <code>model</code>, ...). Once the configuration
- is complete, calling the <code>build</code> method would create the least squares problem.
- </p>
- <p>
- The factory utility is better suited when the various elements of the least squares
- problem are all known at one place and the problem can be built in just one sweep, calling
- to one of the static <code>LeastSquaresFactory.create</code> method.
- </p>
- </subsection>
-
- <subsection name="14.3 Model Function">
- <p>
- The model function is used by the least squares engine to evaluate the model components
- model<sub>i</sub> given some test parameters p<sub>k</sub>. It is therefore a multivariate
- function (it depends on the various p<sub>k</sub>) and it is vector-valued (it has several
- components model<sub>i</sub>). There must be exactly one component model<sub>i</sub> for
- each target (or observed) component target<sub>i</sub>, otherwise some residuals to be
- squared and summed could not be computed. In order for the problem to be well defined, the
- number of parameters p<sub>k</sub> must be less than the number of components model<sub>i</sub>.
- Failing to ensure this may lead to the engine throwing an exception as the underlying linear
- algebra operations may encounter singular matrices. It is not unusual to have a large number
- of components (several thousands) and only a dozen parameters. There are no limitations on these
- numbers, though.
- </p>
- <p>
- As the least squares engine needs to create Jacobians matrices for the model function, both
- its value and its derivatives <em>with respect to the p<sub>k</sub> parameters</em> must
- be available. There are two ways to provide this:
- <ul>
- <li>provide one
- <a href="../apidocs/org/apache/commons/math4/analysis/MultivariateVectorFunction.html">MultivariateVectorFunction</a>
- instance for computing the components values and one
- <a href="../apidocs/org/apache/commons/math4/analysis/MultivariateMatrixFunction.html">MultivariateMatrixFunction</a>
- instance for computing the components derivatives (i.e. the Jacobian matrix) with
- respect to the parameters,</li>
- <li>or provide one
- <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/MultivariateJacobianFunction.html">MultivariateJacobianFunction</a>
- instance for computing both the components values and their derivatives simultaneously.</li>
- </ul>
- The first alternative is best suited for models which are not computationally intensive
- as it allows more modularized code with one method for each type of computation. The second
- alternative is best suited for models which are computationally intensive and evaluating
- both the values and derivatives in one sweep saves a lot of work.
- </p>
- <p>
- The <code>point</code> parameter of the <code>value</code> methods in the
- <a href="../apidocs/org/apache/commons/math4/analysis/MultivariateVectorFunction.html">MultivariateVectorFunction</a>,
- <a href="../apidocs/org/apache/commons/math4/analysis/MultivariateMatrixFunction.html">MultivariateMatrixFunction</a>,
- or <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/MultivariateJacobianFunction.html">MultivariateJacobianFunction</a>
- interfaces will contain the parameters p<sub>k</sub>. The values will be the model components
- model<sub>i</sub> and the derivatives will be the derivatives of the model components
- with respect to the parameters dmodel<sub>i</sub>/dp<sub>k</sub>.
- </p>
- <p>
- There are no requirements on how to compute value and derivatives. The
- <a href="../apidocs/org/apache/commons/math4/analysis/differentiation/DerivativeStructure.html">
- DerivativeStructure</a> class may be useful to compute analytically derivatives in
- difficult cases, but this class is not mandated by the API which only expects the derivatives
- as a Jacobian matrix containing primitive double entries.
- </p>
- <p>
- One non-obvious feature provided by both the builder and the factory is lazy evaluation. This feature
- allows to defer calls to the model functions until they are really needed by the engine. This
- can save some calls for engines that evaluate the value and the Jacobians in different loops
- (this is the case for Levenberg-Marquardt). However, lazy evaluation is possible <em>only</em>
- if the model functions are themselves separated, i.e. it can be used only with the first
- alternative above. Setting up the <code>lazyEvaluation</code> flag to <code>true</code> in the builder
- or factory and setting up the model function as one
- <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/MultivariateJacobianFunction.html">MultivariateJacobianFunction</a>
- instance at the same time will trigger an illegal state exception telling that the model function
- misses required functionality.
- </p>
- </subsection>
-
- <subsection name="14.4 Parameters Validation">
- <p>
- In some cases, the model function requires parameters to lie within a specific domain. For example
- a parameter may be used in a square root and needs to be positive, or another parameter represents
- the sine of an angle and should be within -1 and +1, or several parameters may need to remain in
- the unit circle and the sum of their squares must be smaller than 1. The least square solvers available
- in Apache Commons Math currently don't allow to set up constraints on the parameters. This is a
- known missing feature. There are two ways to circumvent this.
- </p>
- <p>
- Both ways are achieved by setting up a
- <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/ParameterValidator.html">ParameterValidator</a>
- instance. The input of the value and jacobian model functions will always be the output of
- the parameter validator if one exists.
- </p>
- <p>
- One way to constrain parameters is to use a continuous mapping between the parameters that the
- least squares solver will handle and the real parameters of the mathematical model. Using mapping
- functions like <code>logit</code> and <code>sigmoid</code>, one can map a finite range to the
- infinite real line. Using mapping functions based on <code>log</code> and <code>exp</code>, one
- can map a semi-infinite range to the infinite real line. It is possible to use such a mapping so
- that the engine will always see unbounded parameters, whereas on the other side of the mapping the
- mathematical model will always see parameters mapped correctly to the expected range. Care must be
- taken with derivatives as one must remember that the parameters have been mapped. Care must also
- be taken with convergence status. This may be tricky.
- </p>
- <p>
- Another way to constrain parameters is to simply truncate the parameters back to the domain when
- one search point escapes from it and not care about derivatives. This works <em>only</em> if the
- solution is expected to be inside the domain and not at the boundary, as points out of the domain
- will only be temporary test points with a cost function higher than the real solution and will soon
- be dropped by the underlying engine. As a rule of thumb, these conditions are met only when the
- domain boundaries correspond to unrealistic values that will never be achieved (null distances,
- negative masses, ...) but they will not be met when the domain boundaries are more operational
- limits (a maximum weight that can be handled by a device, a minimum temperature that can be
- sustained by an instrument, ...).
- </p>
- </subsection>
-
- <subsection name="14.5 Tuning">
- <p>
- Among the elements to be provided to the least squares problem builder or factory
- are some tuning parameters for the solver.
- </p>
- <p>
- The maximum number of iterations refers to the engine algorithm main loop, whereas the
- maximum number of iterations refers to the number of calls to the model method. Some
- algorithms (like Levenberg-Marquardt) have two embedded loops, with iteration number
- being incremented at outer loop level, but a new evaluation being done at each inner
- loop. In this case, the number of evaluations will be greater than the number of iterations.
- Other algorithms (like Gauss-Newton) have only one level of loops. In this case, the
- number of evaluations will equal to the number of iterations. In any case, the maximum
- numbers are really only intended as safeguard to prevent infinite loops, so the exact
- value of the limit is not important so it is common to select some almost arbitrary number
- much larger than the expected number of evaluations and use it for both
- <code>maxIterations</code> and <code>maxEvaluations</code>. As an example, if the least
- squares solver usually finds a solution in 50 iterations, setting a maximum value to 1000
- is probably safe and prevents infinite loops. If the least squares solver needs several
- hundreds of evaluations, it would probably be safer to set the maximum value to 10000 or
- even 1000000 to avoid failures in slightly more demanding cases. Very fine tuning of
- these maximum numbers is often worthless, they are only intended as safeguards.
- </p>
- <p>
- Convergence checking is delegated to a dedicated interface from the <code>optim</code>
- package: <a href="../apidocs/org/apache/commons/math4/optim/ConvergenceChecker.html">
- ConvergenceChecker</a>, parameterized with either the specific
- <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/LeastSquaresProblem.Evaluation.html">Evaluation</a>
- class used for least squares problems or the general
- <a href="../apidocs/org/apache/commons/math4/optim/PointVectorValuePair.html">PointVectorValuePair</a>.
- Each time convergence is checked, both the previous
- and the current evaluations of the least squares problem are provided, so the checker can
- compare them and decide whereas convergence has been reached or not. The predefined convergence
- checker implementations that can be useful for least squares fitting are:
- <ul>
- <li><a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/EvaluationRmsChecker.html">EvaluationRmsChecker</a>,
- which uses only the normalized cost (square-root of the sum of squared of the residuals,
- divided by the number of measurements),</li>
- <li><a href="../apidocs/org/apache/commons/math4/optim/SimpleVectorValueChecker.html">SimpleVectorValueChecker</a>,
- which uses the model components themselves (<em>not</em> the residuals),</li>
- <li><a href="../apidocs/org/apache/commons/math4/optim/SimplePointChecker.html">SimplePointChecker<PointVectorValuePair></a>,
- which uses the parameters.</li>
- </ul>
- Of course, users can also provide their own implementation of the
- <a href="../apidocs/org/apache/commons/math4/optim/ConvergenceChecker.html">ConvergenceChecker</a>
- interface.
- </p>
- </subsection>
-
- <subsection name="14.6 Optimization Engine">
- <p>
- Once the least squares problem has been created, using either the builder or the factory,
- it is passed to an optimization engine for solving. Two engines devoted to least-squares
- problems are available. The first one is
- based on the <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/GaussNewtonOptimizer.html">
- Gauss-Newton</a> method. The second one is the <a
- href="../apidocs/org/apache/commons/math4/fitting/leastsquares/LevenbergMarquardtOptimizer.html">
- Levenberg-Marquardt</a> method. For both increased readability and in order to leverage
- possible future changes in the configuration, it is recommended to use the fluent-style API to
- build and configure the optimizers. This means creating a first temporary version of the optimizer
- with a default parameterless constructor, and then to set up the various configuration parameters
- using the available <code>withXxx</code> methods that all return a new optimizer instance. Only the
- final fully configured instance is used. As an example, setting up a Levenberg-Marquardt with
- all configuration set to default except the cost relative tolerance and parameter relative tolerance
- would be done as follows:
- </p>
- <source>
- LeastSquaresOptimizer optimizer = new LevenbergMarquardtOptimizer().
- withCostRelativeTolerance(1.0e-12).
- withParameterRelativeTolerance(1.0e-12);
- </source>
-
- <p>
- As another example, setting up a Gauss-Newton optimizer and forcing the decomposition to SVD (the
- default is QR decomposition) would be done as follows:
- </p>
- <source>
- LeastSquaresOptimizer optimizer = new GaussNewtonOptimizer().
- withwithDecomposition(GaussNewtonOptimizer.Decomposition.QR);
- </source>
-
- </subsection>
-
- <subsection name="14.7 Solving">
- <p>
- Solving the least squares problem is done by calling the <code>optimize</code> method of the
- optimizer and passing the least squares problem as the single parameter:
- </p>
- <source>
- LeastSquaresOptimizer.Optimum optimum = optimizer.optimize(leastSquaresProblem);
- </source>
-
- <p>
- The <a
- href="../apidocs/org/apache/commons/math4/fitting/leastsquares/LeastSquaresOptimizer.Optimum.html">
- LeastSquaresOptimizer.Optimum</a> class is a specialized
- <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/LeastSquaresProblem.Evaluation.html">Evaluation</a>
- with additional methods te retrieve the number of evaluations and number of iterations performed.
- The most important methods are inherited from the
- <a href="../apidocs/org/apache/commons/math4/fitting/leastsquares/LeastSquaresProblem.Evaluation.html">Evaluation</a>
- class and correspond to the point (i.e. the parameters), cost, Jacobian, RMS, covariance ...
- </p>
- </subsection>
-
- <subsection name="14.8 Example">
- <p>
- The following simple example shows how to find the center of a circle of known radius to
- to best fit observed 2D points. It is a simplified version of one of the JUnit test cases.
- In the complete test case, both the circle center and its radius are fitted, here the
- radius is fixed.
- </p>
- <source>
- final double radius = 70.0;
- final Vector2D[] observedPoints = new Vector2D[] {
- new Vector2D( 30.0, 68.0),
- new Vector2D( 50.0, -6.0),
- new Vector2D(110.0, -20.0),
- new Vector2D( 35.0, 15.0),
- new Vector2D( 45.0, 97.0)
- };
-
- // the model function components are the distances to current estimated center,
- // they should be as close as possible to the specified radius
- MultivariateJacobianFunction distancesToCurrentCenter = new MultivariateJacobianFunction() {
- public Pair<RealVector, RealMatrix> value(final RealVector point) {
-
- Vector2D center = new Vector2D(point.getEntry(0), point.getEntry(1));
-
- RealVector value = new ArrayRealVector(observedPoints.length);
- RealMatrix jacobian = new Array2DRowRealMatrix(observedPoints.length, 2);
-
- for (int i = 0; i < observedPoints.length; ++i) {
- Vector2D o = observedPoints[i];
- double modelI = Vector2D.distance(o, center);
- value.setEntry(i, modelI);
- // derivative with respect to p0 = x center
- jacobian.setEntry(i, 0, (center.getX() - o.getX()) / modelI);
- // derivative with respect to p1 = y center
- jacobian.setEntry(i, 1, (center.getX() - o.getX()) / modelI);
- }
-
- return new Pair<RealVector, RealMatrix>(value, jacobian);
-
- }
- };
-
- // the target is to have all points at the specified radius from the center
- double[] prescribedDistances = new double[observedPoints.length];
- Arrays.fill(prescribedDistances, radius);
-
- // least squares problem to solve : modeled radius should be close to target radius
- LeastSquaresProblem problem = new LeastSquaresBuilder().
- start(new double[] { 100.0, 50.0 }).
- model(distancesToCurrentCenter).
- target(prescribedDistances).
- lazyEvaluation(false).
- maxEvaluations(1000).
- maxIterations(1000).
- build();
- LeastSquaresOptimizer.Optimum optimum = new LevenbergMarquardtOptimizer().optimize(problem);
- Vector2D fittedCenter = new Vector2D(optimum.getPoint().getEntry(0), optimum.getPoint().getEntry(1));
- System.out.println("fitted center: " + fittedCenter.getX() + " " + fittedCenter.getY());
- System.out.println("RMS: " + optimum.getRMS());
- System.out.println("evaluations: " + optimum.getEvaluations());
- System.out.println("iterations: " + optimum.getIterations());
- </source>
- </subsection>
-
- </section>
- </body>
-</document>
[2/5] commons-numbers git commit: NUMBERS-70: Delete files describing
"Commons Math" (userguide).
Posted by er...@apache.org.
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/random.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/random.xml b/src/site/xdoc/userguide/random.xml
deleted file mode 100644
index 1ea7615..0000000
--- a/src/site/xdoc/userguide/random.xml
+++ /dev/null
@@ -1,563 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="random.html">
-
-<properties>
- <title>The Commons Math User Guide - Data Generation</title>
-</properties>
-
-<body>
-
-<section name="2 Data Generation">
-
-<subsection name="2.1 Overview" href="overview">
- <p>
- The Commons Math random package includes utilities for
- <ul>
- <li>generating random numbers</li>
- <li>generating random vectors</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. Other very
- good PRNG suitable for Monte-Carlo analysis (but <strong>not</strong>
- for cryptography) provided by the library are the Mersenne twister from
- Makoto Matsumoto and Takuji Nishimura and the more recent WELL generators
- (Well Equidistributed Long-period Linear) from François Panneton, Pierre
- L'Ecuyer and Makoto Matsumoto.
- </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>
-</subsection>
-
-<subsection name="2.2 Random numbers" href="deviates">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/random/RandomDataGenerator.html">
- RandomDataGenerator</a> class implements 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">
- 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">
- 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 each of the distributions in the
- <a href="../apidocs/org/apache/commons/math4/distribution/package-summary.html">
- distributions</a> package.
- The javadoc for the <code>nextXxx</code> methods in
- <a href="../apidocs/org/apache/commons/math4/random/RandomDataGenerator.html">
- RandomDataGenerator</a> describes the algorithms used to generate
- random deviates.
- </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">
- secure random number generator</a> to generate values (or strings). The
- nextSecureXxx methods implemented by <code>RandomDataGenerator</code>
- 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. The <code>ISAACRandom</code> class implements a fast
- cryptographically secure pseudorandom number generator.</dd>
- <dt>Seeding pseudo-random number generators</dt>
- <dd>By default, the implementation provided in <code>RandomDataGenerator</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>RandomDataGenerator</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> RandomDataGenerator</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:
- <source>
-RandomDataGenerator randomData = new RandomDataGenerator();
-for (int i = 0; i < 1000; i++) {
- value = randomData.nextLong(1, 1000000);
-}
- </source>
- 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:
- <source>
-for (int i = 0; i < 1000; i++) {
- RandomDataGenerator randomData = new RandomDataGenerator();
- value = randomData.nextLong(1, 1000000);
-}
- </source>
- The following will produce the same random sequence each time it is
- executed:
- <source>
-RandomDataGenerator randomData = new RandomDataGenerator();
-randomData.reSeed(1000);
-for (int i = 0; i = 1000; i++) {
- value = randomData.nextLong(1, 1000000);
-}
- </source>
- The following will produce a different random sequence each time it is
- executed.
- <source>
-RandomDataGenerator randomData = new RandomDataGenerator();
-randomData.reSeedSecure(1000);
-for (int i = 0; i < 1000; i++) {
- value = randomData.nextSecureLong(1, 1000000);
-}
- </source>
- </dd></dl>
- </p>
-</subsection>
-
-<subsection name="2.3 Random Vectors" href="vectors">
- <p>
- Some algorithms require 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/math4/random/UncorrelatedRandomVectorGenerator.html">
- UncorrelatedRandomVectorGenerator</a> class simplifies 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/math4/random/CorrelatedRandomVectorGenerator.html">
- 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">
- Multivariate Normal Distribution</a>.
- </p>
- <p><dl>
- <dt>Generating random vectors from a bivariate normal distribution</dt><dd>
- <source>
-// Create and seed a RandomGenerator (could use any of the generators in the random package here)
-RandomGenerator rg = new JDKRandomGenerator();
-rg.setSeed(17399225432l); // Fixed seed means same results every time
-
-// Create a GassianRandomGenerator using rg as its source of randomness
-GaussianRandomGenerator rawGenerator = new GaussianRandomGenerator(rg);
-
-// Create a CorrelatedRandomVectorGenerator using rawGenerator for the components
-CorrelatedRandomVectorGenerator generator =
- new CorrelatedRandomVectorGenerator(mean, covariance, 1.0e-12 * covariance.getNorm(), rawGenerator);
-
-// Use the generator to generate correlated vectors
-double[] randomVector = generator.nextVector();
-... </source>
- The <code>mean</code> argument is a double[] array holding the means of the random vector
- components. In the bivariate case, it must have length 2. The <code>covariance</code> argument
- is a RealMatrix, which needs to be 2 x 2. The main diagonal elements are the
- variances of the vector components and the off-diagonal elements are the covariances.
- For example, if the means are 1 and 2 respectively, and the desired standard deviations
- are 3 and 4, respectively, then we need to use
- <source>
-double[] mean = {1, 2};
-double[][] cov = {{9, c}, {c, 16}};
-RealMatrix covariance = MatrixUtils.createRealMatrix(cov); </source>
- where c is the desired covariance. If you are starting with a desired correlation,
- you need to translate this to a covariance by multiplying it by the product of the
- standard deviations. For example, if you want to generate data that will give Pearson's
- R of 0.5, you would use c = 3 * 4 * .5 = 6.
- </dd></dl></p>
- <p>
- In addition to multivariate normal distributions, correlated vectors from multivariate uniform
- distributions can be generated by creating a
- <a href="../apidocs/org/apache/commons/math4/random/UniformRandomGenerator.html">UniformRandomGenerator</a>
- in place of the
- <code>GaussianRandomGenerator</code> above. More generally, any
- <a href="../apidocs/org/apache/commons/math4/random/NormalizedRandomGenerator.html">NormalizedRandomGenerator</a>
- may be used.
- </p>
- <p><dl>
- <dt>Low discrepancy sequences</dt>
- <dd>
- There exist several quasi-random sequences with the property that for all values of N, the subsequence
- x<sub>1</sub>, ..., x<sub>N</sub> has low discrepancy, which results in equi-distributed samples.
- While their quasi-randomness makes them unsuitable for most applications (i.e. the sequence of values
- is completely deterministic), their unique properties give them an important advantage for quasi-Monte Carlo simulations.<br/>
- Currently, the following low-discrepancy sequences are supported:
- <ul>
- <li><a href="../apidocs/org/apache/commons/math4/random/SobolSequenceGenerator.html">Sobol sequence</a> (pre-configured up to dimension 1000)</li>
- <li><a href="../apidocs/org/apache/commons/math4/random/HaltonSequenceGenerator.html">Halton sequence</a> (pre-configured up to dimension 40)</li>
- </ul>
- <source>
-// Create a Sobol sequence generator for 2-dimensional vectors
-RandomVectorGenerator generator = new SobolSequence(2);
-
-// Use the generator to generate vectors
-double[] randomVector = generator.nextVector();
-... </source>
- The figure below illustrates the unique properties of low-discrepancy sequences when generating N samples
- in the interval [0, 1]. Roughly speaking, such sequences "fill" the respective space more evenly which leads to faster convergence in
- quasi-Monte Carlo simulations.<br/>
- <img src="../images/userguide/low_discrepancy_sequences.png" alt="Comparison of low-discrepancy sequences"/>
- </dd></dl>
- </p>
- <p></p>
-</subsection>
-
-<subsection name="2.4 Random Strings" href="strings">
- <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>RandomDataGenerator</code> uses the
- following simple algorithm to generate a string of <code>n</code> hex digits:
- <ol>
- <li>n/2+1 binary bytes are generated using the underlying RandomGenerator</li>
- <li>Each binary byte is translated into 2 hex digits</li></ol>
- The <code>RandomDataGenerator</code> implementation of the "secure" version,
- <code>nextSecureHexString</code> generates hex characters in 40-byte
- "chunks" using a 3-step process:
- <ol>
- <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>
-</subsection>
-
-<subsection name="2.5 Random permutations, combinations, sampling"
- href="combinatorics">
- <p>
- To select a random sample of objects in a collection, you can use the
- <code>nextSample</code> method implemented by <code>RandomDataGenerator</code>.
- Specifically, if <code>c</code> is a collection containing at least
- <code>k</code> objects, and <code>randomData</code> is a
- <code>RandomDataGenerator</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>RandomDataGenerator</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>
-</subsection>
-
-<subsection name="2.6 Generating data 'like' an input file" href="empirical">
- <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.
- <source>
- 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();
- </source>
- 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">
- 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:
- <source>
- 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...
- </source>
- 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>
-</subsection>
-
-<subsection name="2.7 PRNG Pluggability" href="pluggability">
- <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/math4/random/RandomGenerator.html">
- 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/math4/random/AbstractRandomGenerator.html">
- 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/math4/random/RandomAdaptor.html">
- 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>Commons-math provides by itself several implementations of the <a
- href="../apidocs/org/apache/commons/math4/random/RandomGenerator.html">
- RandomGenerator</a> interface:
- <ul>
- <li><a href="../apidocs/org/apache/commons/math4/random/JDKRandomGenerator.html">JDKRandomGenerator</a>
- that extends the JDK provided generator</li>
- <li><a href="../apidocs/org/apache/commons/math4/random/AbstractRandomGenerator.html">
- AbstractRandomGenerator</a> as a helper for users generators</li>
- <li><a href="../apidocs/org/apache/commons/math4/random/BitStreamGenerator.html">
- BitStreamGenerator</a> which is an abstract class for several generators and
- which in turn is extended by:
- <ul>
- <li><a href="../apidocs/org/apache/commons/math4/random/MersenneTwister.html">MersenneTwister</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/random/Well512a.html">Well512a</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/random/Well1024a.html">Well1024a</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/random/Well19937a.html">Well19937a</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/random/Well19937c.html">Well19937c</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/random/Well44497a.html">Well44497a</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/random/Well44497b.html">Well44497b</a></li>
- </ul>
- </li>
- </ul>
- </p>
-
- <p>
- The JDK provided generator is a simple one that can be used only for very simple needs.
- The Mersenne Twister is a fast generator with very good properties well suited for
- Monte-Carlo simulation. It is equidistributed for generating vectors up to dimension 623
- and has a huge period: 2<sup>19937</sup> - 1 (which is a Mersenne prime). This generator
- is described in a paper by Makoto Matsumoto and Takuji Nishimura in 1998: <a
- href="http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/ARTICLES/mt.pdf">Mersenne Twister:
- A 623-Dimensionally Equidistributed Uniform Pseudo-Random Number Generator</a>, ACM
- Transactions on Modeling and Computer Simulation, Vol. 8, No. 1, January 1998, pp 3--30.
- The WELL generators are a family of generators with period ranging from 2<sup>512</sup> - 1
- to 2<sup>44497</sup> - 1 (this last one is also a Mersenne prime) with even better properties
- than Mersenne Twister. These generators are described in a paper by François Panneton,
- Pierre L'Ecuyer and Makoto Matsumoto <a
- href="http://www.iro.umontreal.ca/~lecuyer/myftp/papers/wellrng.pdf">Improved Long-Period
- Generators Based on Linear Recurrences Modulo 2</a> ACM Transactions on Mathematical Software,
- 32, 1 (2006). The errata for the paper are in <a
- href="http://www.iro.umontreal.ca/~lecuyer/myftp/papers/wellrng-errata.txt">wellrng-errata.txt</a>.
- </p>
-
- <p>
- For simple sampling, any of these generators is sufficient. For Monte-Carlo simulations the
- JDK generator does not have any of the good mathematical properties of the other generators,
- so it should be avoided. The Mersenne twister and WELL generators have equidistribution properties
- proven according to their bits pool size which is directly linked to their period (all of them
- have maximal period, i.e. a generator with size n pool has a period 2<sup>n</sup>-1). They also
- have equidistribution properties for 32 bits blocks up to s/32 dimension where s is their pool size.
- So WELL19937c for exemple is equidistributed up to dimension 623 (19937/32). This means a Monte-Carlo
- simulation generating a vector of n variables at each iteration has some guarantees on the properties
- of the vector as long as its dimension does not exceed the limit. However, since we use bits from two
- successive 32 bits generated integers to create one double, this limit is smaller when the variables are
- of type double. so for Monte-Carlo simulation where less the 16 doubles are generated at each round,
- WELL1024 may be sufficient. If a larger number of doubles are needed a generator with a larger pool
- would be useful.
- </p>
-
- <p>
- The WELL generators are more modern then MersenneTwister (the paper describing than has been published
- in 2006 instead of 1998) and fix some of its (few) drawbacks. If initialization array contains many
- zero bits, MersenneTwister may take a very long time (several hundreds of thousands of iterations to
- reach a steady state with a balanced number of zero and one in its bits pool). So the WELL generators
- are better to <i>escape zeroland</i> as explained by the WELL generators creators. The Well19937a and
- Well44497a generator are not maximally equidistributed (i.e. there are some dimensions or bits blocks
- size for which they are not equidistributed). The Well512a, Well1024a, Well19937c and Well44497b are
- maximally equidistributed for blocks size up to 32 bits (they should behave correctly also for double
- based on more than 32 bits blocks, but equidistribution is not proven at these blocks sizes).
- </p>
-
- <p>
- The MersenneTwister generator uses a 624 elements integer array, so it consumes less than 2.5 kilobytes.
- The WELL generators use 6 integer arrays with a size equal to the pool size, so for example the
- WELL44497b generator uses about 33 kilobytes. This may be important if a very large number of
- generator instances were used at the same time.
- </p>
-
- <p>
- All generators are quite fast. As an example, here are some comparisons, obtained on a 64 bits JVM on a
- linux computer with a 2008 processor (AMD phenom Quad 9550 at 2.2 GHz). The generation rate for
- MersenneTwister was between 25 and 27 millions doubles per second (remember we generate two 32 bits integers for
- each double). Generation rates for other PRNG, relative to MersenneTwister:
- </p>
-
- <p>
- <table border="1" align="center">
- <tr BGCOLOR="#CCCCFF"><td colspan="2"><font size="+1">Example of performances</font></td></tr>
- <tr BGCOLOR="#EEEEFF"><font size="+1"><td>Name</td><td>generation rate (relative to MersenneTwister)</td></font></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/random/MersenneTwister.html">MersenneTwister</a></td><td>1</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/random/JDKRandomGenerator.html">JDKRandomGenerator</a></td><td>between 0.96 and 1.16</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/random/Well512a.html">Well512a</a></td><td>between 0.85 and 0.88</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/random/Well1024a.html">Well1024a</a></td><td>between 0.63 and 0.73</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/random/Well19937a.html">Well19937a</a></td><td>between 0.70 and 0.71</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/random/Well19937c.html">Well19937c</a></td><td>between 0.57 and 0.71</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/random/Well44497a.html">Well44497a</a></td><td>between 0.69 and 0.71</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/random/Well44497b.html">Well44497b</a></td><td>between 0.65 and 0.71</td></tr>
- </table>
- </p>
-
- <p>
- So for most simulation problems, the better generators like <a
- href="../apidocs/org/apache/commons/math4/random/Well19937c.html">Well19937c</a> and <a
- href="../apidocs/org/apache/commons/math4/random/Well44497b.html">Well44497b</a> are probably very good choices.
- </p>
-
- <p>
- Note that <em>none</em> of these generators are suitable for cryptography. They are devoted
- to simulation, and to generate very long series with strong properties on the series as a whole
- (equidistribution, no correlation ...). They do not attempt to create small series but with
- very strong properties of unpredictability as needed in cryptography.
- </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:
- <source>
-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();
- }
-}
- </source>
- </dd>
- <dt>Use the Mersenne Twister RandomGenerator in place of
- <code>java.util.Random</code> in <code>RandomData</code></dt>
- <dd>
- <source>
-RandomData randomData = new RandomDataImpl(new RngPackGenerator());
- </source>
- </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>
- <source>
- 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
- </source>
- </dd>
- </dl>
- </p>
-</subsection>
-
-</section>
-
-</body>
-</document>
[3/5] commons-numbers git commit: NUMBERS-70: Delete files describing
"Commons Math" (userguide).
Posted by er...@apache.org.
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/linear.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/linear.xml b/src/site/xdoc/userguide/linear.xml
deleted file mode 100644
index 3a061e3..0000000
--- a/src/site/xdoc/userguide/linear.xml
+++ /dev/null
@@ -1,212 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="linear.html">
-
- <properties>
- <title>The Commons Math User Guide - Linear Algebra</title>
- </properties>
-
- <body>
- <section name="3 Linear Algebra">
- <subsection name="3.1 Overview" href="overview">
- <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>
- </subsection>
- <subsection name="3.2 Real matrices" href="real_matrices">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/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:
- <source>
-// Create a real matrix with two rows and three columns, using a factory
-// method that selects the implementation class for us.
-double[][] matrixData = { {1d,2d,3d}, {2d,5d,3d}};
-RealMatrix m = MatrixUtils.createRealMatrix(matrixData);
-
-// One more with three rows, two columns, this time instantiating the
-// RealMatrix implementation class directly.
-double[][] matrixData2 = { {1d,2d}, {2d,5d}, {1d, 7d}};
-RealMatrix n = new Array2DRowRealMatrix(matrixData2);
-
-// Note: The constructor copies the input double[][] array in both cases.
-
-// 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 LUDecomposition(p).getSolver().getInverse();
- </source>
- </p>
- <p>
- The three main implementations of the interface are <a
- href="../apidocs/org/apache/commons/math4/linear/Array2DRowRealMatrix.html">
- Array2DRowRealMatrix</a> and <a
- href="../apidocs/org/apache/commons/math4/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/math4/linear/SparseRealMatrix.html">
- SparseRealMatrix</a> for sparse matrices.
- </p>
- </subsection>
- <subsection name="3.3 Real vectors" href="real_vectors">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/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/math4/linear/RealVectorFormat.html">
- RealVectorFormat</a> class handles input/output of vectors in a customizable
- textual format.
- </p>
- </subsection>
- <subsection name="3.4 Solving linear systems" href="solve">
- <p>
- The <code>solve()</code> methods of the <a
- href="../apidocs/org/apache/commons/math4/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
- <source>
-RealMatrix coefficients =
- new Array2DRowRealMatrix(new double[][] { { 2, 3, -2 }, { -1, 7, 6 }, { 4, -3, -5 } },
- false);
-DecompositionSolver solver = new LUDecomposition(coefficients).getSolver();
- </source>
- Next create a <code>RealVector</code> array to represent the constant
- vector B and use <code>solve(RealVector)</code> to solve the system
- <source>
-RealVector constants = new ArrayRealVector(new double[] { 1, -2, 1 }, false);
-RealVector solution = solver.solve(constants);
- </source>
- 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. Least Square sense means a solver can be computed
- for an overdetermined system, (i.e. a system with more equations than unknowns,
- which corresponds to a tall A matrix with more rows than columns). 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. In any case, if the matrix is singular
- within the tolerance set at construction, an error will be triggered when
- the solve method will be called, both for algorithms that compute exact solutions
- and for algorithms that compute least square solutions.
- </p>
- <p>
- <table border="1" align="center">
- <tr BGCOLOR="#CCCCFF"><td colspan="3"><font size="+1">Decomposition algorithms</font></td></tr>
- <tr BGCOLOR="#EEEEFF"><font size="+1"><td>Name</td><td>coefficients matrix</td><td>problem type</td></font></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/linear/LUDecomposition.html">LU</a></td><td>square</td><td>exact solution only</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/linear/CholeskyDecomposition.html">Cholesky</a></td><td>symmetric positive definite</td><td>exact solution only</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/linear/QRDecomposition.html">QR</a></td><td>any</td><td>least squares solution</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/linear/EigenDecomposition.html">eigen decomposition</a></td><td>square</td><td>exact solution only</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/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>
- </subsection>
- <subsection name="3.5 Eigenvalues/eigenvectors and singular values/singular vectors" href="eigen">
- <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>
- </subsection>
- <subsection name="3.6 Non-real fields (complex, fractions ...)" href="field">
- <p>
- In addition to the real field, matrices and vectors using non-real <a
- href="../apidocs/org/apache/commons/math4/FieldElement.html">field elements</a> can be used.
- The fields already supported by the library are:
- <ul>
- <li><a href="../apidocs/org/apache/commons/math4/complex/Complex.html">Complex</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/fraction/Fraction.html">Fraction</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/fraction/BigFraction.html">BigFraction</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/util/BigReal.html">BigReal</a></li>
- </ul>
- </p>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/ml.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/ml.xml b/src/site/xdoc/userguide/ml.xml
deleted file mode 100644
index bc3f2c2..0000000
--- a/src/site/xdoc/userguide/ml.xml
+++ /dev/null
@@ -1,146 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="ml.html">
-
- <properties>
- <title>The Commons Math User Guide - Machine Learning</title>
- </properties>
-
- <body>
- <section name="16 Machine Learning">
- <subsection name="16.1 Overview" href="overview">
- <p>
- Machine learning support in commons-math currently provides operations to cluster
- data sets based on a distance measure.
- </p>
- </subsection>
- <subsection name="16.2 Clustering algorithms and distance measures" href="clustering">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/ml/clustering/Clusterer.html">
- Clusterer</a> class represents a clustering algorithm.
- The following algorithms are available:
- <ul>
- <li><a href="../apidocs/org/apache/commons/math4/ml/clustering/KMeansPlusPlusClusterer.html">KMeans++</a>:
- It is based on the well-known kMeans algorithm, but uses a different method for
- choosing the initial values (or "seeds") and thus avoids cases where KMeans sometimes
- results in poor clusterings. KMeans/KMeans++ clustering aims to partition n observations
- into k clusters in such that each point belongs to the cluster with the nearest center.
- </li>
- <li><a href="../apidocs/org/apache/commons/math4/ml/clustering/FuzzyKMeansClusterer.html">Fuzzy-KMeans</a>:
- A variation of the classical K-Means algorithm, with the major difference that a single
- data point is not uniquely assigned to a single cluster. Instead, each point i has a set
- of weights u<sub>ij</sub> which indicate the degree of membership to the cluster j. The fuzzy
- variant does not require initial values for the cluster centers and is thus more robust, although
- slower than the original kMeans algorithm.
- </li>
- <li><a href="../apidocs/org/apache/commons/math4/ml/clustering/DBSCANClusterer.html">DBSCAN</a>:
- Density-based spatial clustering of applications with noise (DBSCAN) finds a number of
- clusters starting from the estimated density distribution of corresponding nodes. The
- main advantages over KMeans/KMeans++ are that DBSCAN does not require the specification
- of an initial number of clusters and can find arbitrarily shaped clusters.
- </li>
- <li><a href="../apidocs/org/apache/commons/math4/ml/clustering/MultiKMeansPlusPlusClusterer.html">Multi-KMeans++</a>:
- Multi-KMeans++ is a meta algorithm that basically performs n runs using KMeans++ and then
- chooses the best clustering (i.e., the one with the lowest distance variance over all clusters)
- from those runs.
- </li>
- </ul>
- </p>
- <p>
- An comparison of the available clustering algorithms:<br/>
- <img src="../images/userguide/cluster_comparison.png" alt="Comparison of clustering algorithms"/>
- </p>
- </subsection>
- <subsection name="16.3 Distance measures" href="distance">
- <p>
- Each clustering algorithm requires a distance measure to determine the distance
- between two points (either data points or cluster centers).
- The following distance measures are available:
- <ul>
- <li><a href="../apidocs/org/apache/commons/math4/ml/distance/CanberraDistance.html">Canberra distance</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/ml/distance/ChebyshevDistance.html">ChebyshevDistance distance</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/ml/distance/EuclideanDistance.html">EuclideanDistance distance</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/ml/distance/ManhattanDistance.html">ManhattanDistance distance</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/ml/distance/EarthMoversDistance.html">Earth Mover's distance</a></li>
- </ul>
- </p>
- </subsection>
- <subsection name="16.3 Example" href="example">
- <p>
- Here is an example of a clustering execution. Let us assume we have a set of locations from our domain model,
- where each location has a method <code>double getX()</code> and <code>double getY()</code>
- representing their current coordinates in a 2-dimensional space. We want to cluster the locations into
- 10 different clusters based on their euclidean distance.
- </p>
- <p>
- The cluster algorithms expect a list of <a href="../apidocs/org/apache/commons/math4/ml/cluster/Clusterable.html">Clusterable</a>
- as input. Typically, we don't want to pollute our domain objects with interfaces from helper APIs.
- Hence, we first create a wrapper object:
- <source>
-// wrapper class
-public static class LocationWrapper implements Clusterable {
- private double[] points;
- private Location location;
-
- public LocationWrapper(Location location) {
- this.location = location;
- this.points = new double[] { location.getX(), location.getY() }
- }
-
- public Location getLocation() {
- return location;
- }
-
- public double[] getPoint() {
- return points;
- }
-}
- </source>
- Now we will create a list of these wrapper objects (one for each location),
- which serves as input to our clustering algorithm.
- <source>
-// we have a list of our locations we want to cluster. create a
-List<Location> locations = ...;
-List<LocationWrapper> clusterInput = new ArrayList<LocationWrapper>(locations.size());
-for (Location location : locations)
- clusterInput.add(new LocationWrapper(location));
- </source>
- Finally, we can apply our clustering algorithm and output the found clusters.
- <source>
-// initialize a new clustering algorithm.
-// we use KMeans++ with 10 clusters and 10000 iterations maximum.
-// we did not specify a distance measure; the default (euclidean distance) is used.
-KMeansPlusPlusClusterer<LocationWrapper> clusterer = new KMeansPlusPlusClusterer<LocationWrapper>(10, 10000);
-List<CentroidCluster<LocationWrapper>> clusterResults = clusterer.cluster(clusterInput);
-
-// output the clusters
-for (int i=0; i<clusterResults.size(); i++) {
- System.out.println("Cluster " + i);
- for (LocationWrapper locationWrapper : clusterResults.get(i).getPoints())
- System.out.println(locationWrapper.getLocation());
- System.out.println();
-}
- </source>
- </p>
- </subsection>
- </section>
- </body>
-</document>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/ode.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/ode.xml b/src/site/xdoc/userguide/ode.xml
deleted file mode 100644
index 4d20b1f..0000000
--- a/src/site/xdoc/userguide/ode.xml
+++ /dev/null
@@ -1,491 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="ode.html">
-
- <properties>
- <title>The Commons Math User Guide - Ordinary Differential Equations Integration</title>
- </properties>
-
- <body>
- <section name="15 Ordinary Differential Equations Integration">
- <subsection name="15.1 Overview" href="overview">
- <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/math4/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>
- All integrators support expanding the main ODE with one or more secondary ODE to manage
- additional state that will be integrated together with the main state. This can be used
- for example to integrate variational equations and compute not only the main state but also
- its partial derivatives with respect to either the initial state or some parameters, these
- derivatives being handled be secondary ODE (see below for an example).
- </p>
- <p>
- Two parallel APIs are available. The first is devoted to solve ode for which the integration free
- variable t and the state y(t) are primitive double and primitive double array respectively. Starting
- with version 3.6, a second API is devoted to solve ode for which the integration free
- variable t and the state y(t) are <code>RealFieldElement</code> and <code>RealFieldElement</code>
- array respectively. This allow for example users to integrate ode where the computation values
- are for example <code>DerivativeStructure</code> elements, hence automatically computing
- partial derivatives with respect to some equations parameters without a need to set up the
- variational equations. Another example is to use <code>Dfp</code> elements in order to solve
- ode with extended precision. As of 3.6, the API are slightly different, mainly in the way they
- handle arrays. Both API will become more similar in 4.0 and future versions as the older
- primitive double API will be modified to match the newer field API. This cannot be done in
- 3.6 for compatibility reasons.
- </p>
- <p>
- The user should describe his problem in his own classes which should implement the
- <a href="../apidocs/org/apache/commons/math4/ode/FirstOrderDifferentialEquations.html">FirstOrderDifferentialEquations</a>
- interface (or <a href="../apidocs/org/apache/commons/math4/ode/FirstOrderFieldDifferentialEquations.html">FirstOrderFieldDifferentialEquations</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/math4/ode/FirstOrderIntegrator.html">FirstOrderIntegrator</a>
- interface (or the <a href="../apidocs/org/apache/commons/math4/ode/FirstOrderFieldIntegrator.html">FirstOrderFieldIntegrator</a>
- interface). The following example shows how to implement the simple two-dimensional problem using double primitives:
- <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>
- <source>
-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]);
- }
-
-}
- </source>
- <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>
- <source>
-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
- </source>
- </subsection>
- <subsection name="15.2 Continuous Output" href="continuous">
- <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/math4/ode/sampling/StepHandler.html">StepHandler</a> interface or a
- <a href="../apidocs/org/apache/commons/math4/ode/sampling/StepNormalizer.html">StepNormalizer</a> object wrapping
- a user-specified object implementing the
- <a href="../apidocs/org/apache/commons/math4/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>
- <source>
-StepHandler stepHandler = new StepHandler() {
- public void init(double t0, double[] y0, double t) {
- }
-
- public void handleStep(StepInterpolator interpolator, boolean isLast) {
- double t = interpolator.getCurrentTime();
- double[] y = interpolator.getInterpolatedState();
- System.out.println(t + " " + y[0] + " " + y[1]);
- }
-};
-integrator.addStepHandler(stepHandler);
- </source>
- <p>
- <a href="../apidocs/org/apache/commons/math4/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/math4/ode/sampling/StepHandler.html">StepHandler</a>
- interface are available for general needs
- (<a href="../apidocs/org/apache/commons/math4/ode/sampling/DummyStepHandler.html">DummyStepHandler</a>,
- <a href="../apidocs/org/apache/commons/math4/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
- of the main state with respect to a specified accuracy (these integrators extend the
- <a href="../apidocs/org/apache/commons/math4/ode/AdaptiveStepsizeIntegrator.html">AdaptiveStepsizeIntegrator</a>
- abstract class). The secondary equations are explicitly ignored for step size control, in order to get reproducible
- results regardless of the secondary equations being integrated or not. The step handler which is called after each
- successful step shows up the variable stepsize. The <a href="../apidocs/org/apache/commons/math4/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/math4/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>
- </subsection>
- <subsection name="15.3 Discrete Events Handling" href="events">
- <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/math4/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.
- For the sake of root finding, it should however be continuous (but not necessarily smooth)
- at least in the roots vicinity. 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>
- <source>
-public double g(double t, double[] y) {
- return y[0] - targetConcentration;
-}
-
-public int eventOccurred(double t, double[] y, boolean increasing) {
- return STOP;
-}
- </source>
-
- <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>
- <source>
-public double g(double t, double[] y) {
- return (t - tManeuverStart) * (t - tManeuverStop);
-}
-
-public int eventOccurred(double t, double[] y, boolean increasing) {
- return RESET_DERIVATIVES;
-}
- </source>
-
- <p>
- The third case is useful mainly for monitoring purposes, a simple example is:
- </p>
- <source>
-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;
-}
- </source>
- </subsection>
- <subsection name="15.4 Available Integrators" href="integrators">
- <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 border="1" align="center">
- <tr BGCOLOR="#CCCCFF"><td colspan="2"><font size="+1">Fixed Step Integrators</font></td></tr>
- <tr BGCOLOR="#EEEEFF"><font size="+1"><td>Name</td><td>Order</td></font></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/EulerIntegrator.html">Euler</a></td><td>1</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/MidpointIntegrator.html">Midpoint</a></td><td>2</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/ClassicalRungeKuttaIntegrator.html">Classical Runge-Kutta</a></td><td>4</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/GillIntegrator.html">Gill</a></td><td>4</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/ThreeEighthesIntegrator.html">3/8</a></td><td>4</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/LutherIntegrator.html">Luther</a></td><td>6</td></tr>
- </table>
- </p>
- <p>
- <table border="1" align="center">
- <tr BGCOLOR="#CCCCFF"><td colspan="3"><font size="+1">Adaptive Stepsize Integrators</font></td></tr>
- <tr BGCOLOR="#EEEEFF"><font size="+1"><td>Name</td><td>Integration Order</td><td>Error Estimation Order</td></font></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/HighamHall54Integrator.html">Higham and Hall</a></td><td>5</td><td>4</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/DormandPrince54Integrator.html">Dormand-Prince 5(4)</a></td><td>5</td><td>4</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/DormandPrince853Integrator.html">Dormand-Prince 8(5,3)</a></td><td>8</td><td>5 and 3</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/GraggBulirschStoerIntegrator.html">Gragg-Bulirsch-Stoer</a></td><td>variable (up to 18 by default)</td><td>variable</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/AdamsBashforthIntegrator.html">Adams-Bashforth</a></td><td>variable</td><td>variable</td></tr>
- <tr><td><a href="../apidocs/org/apache/commons/math4/ode/nonstiff/AdamsMoultonIntegrator.html">Adams-Moulton</a></td><td>variable</td><td>variable</td></tr>
- </table>
- </p>
- </subsection>
- <subsection name="15.5 Derivatives" href="derivatives">
- <p>
- If in addition to state y(t) the user needs to compute the sensitivity of the final state with respect to
- the initial state (dy/dy<sub>0</sub>) or the sensitivity of the final state with respect to some parameters
- of the ODE (dy/dp<sub>k</sub>), he needs to register the variational equations as a set of secondary equations
- appended to the main state before the integration starts. Then the integration will propagate the compound
- state composed of both the main state and its partial derivatives. At the end of the integration, the Jacobian
- matrices are extracted from the integrated secondary state. The <a
- href="../apidocs/org/apache/commons/math4/ode/JacobianMatrices.html">JacobianMatrices</a> class can do most of
- this as long as the local derivatives are provided to it. It will set up the variational equations, register
- them as secondary equations into the ODE, and it will set up the initial values and retrieve the intermediate
- and final values as Jacobian matrices.
- </p>
- <p>
- 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 represent the 6x6
- Jacobian matrix of the final state with respect to the initial state, and the remaining 18 elements will
- represent the 6x3 Jacobian matrix of the final state with respect to the 3 parameters. The <a
- href="../apidocs/org/apache/commons/math4/ode/JacobianMatrices.html">JacobianMatrices</a> class does the mapping
- between the 60 elements compound state and the Jacobian matrices and sets up the correcsponding secondary equations.
- </p>
- <p>
- As the variational equations are considered to be secondary equations here, variable step integrators ignore
- them for step size control: they rely only on the main state. This feature is a design choice. The rationale is
- to get exactly the same steps, regardless of the Jacobians being computed or not, hence ensuring reproducible
- results in both cases.
- </p>
- <p>
- What remains of user responsibility is to provide the local Jacobians df(t, y, p)/dy and df(t, y, p)/dp<sub>k</sub>
- corresponding the the main ODE y'=f(t, y, p). The main ODE is as usual provided by the user as a class implementing
- the <a href="../apidocs/org/apache/commons/math4/ode/FirstOrderDifferentialEquations.html">FirstOrderDifferentialEquations</a>
- interface or a sub-interface.
- </p>
- <p>
- If the ODE is simple enough that the user can implement df(t, y, p)/dy directly, then instead of providing an
- implementation of the <a
- href="../apidocs/org/apache/commons/math4/ode/FirstOrderDifferentialEquations.html">FirstOrderDifferentialEquations</a>
- interface only, the user should rather provide an implementation of the <a
- href="../apidocs/org/apache/commons/math4/ode/MainStateJacobianProvider.html">MainStateJacobianProvider</a> interface,
- which extends the previous interface by adding a method to compute df(t, y, p)/dy. The user class is used as a
- constructor parameter of the <a href="../apidocs/org/apache/commons/math4/ode/JacobianMatrices.html">JacobianMatrices</a>
- class. If the ODE is too complex or the user simply does not bother implementing df(t, y, p)/dy directly, then
- the ODE can still be implemented using the simple <a
- href="../apidocs/org/apache/commons/math4/ode/FirstOrderDifferentialEquations.html">FirstOrderDifferentialEquations</a>
- interface and given as such to another constructor of the <a
- href="../apidocs/org/apache/commons/math4/ode/JacobianMatrices.html">JacobianMatrices</a> class, but in this case an array
- hy must also be provided that will contain the step size to use form each component of the main state vector y, and
- the Jacobian f(t, y, p)/dy will be computed internally using finite differences. This will of course trigger more evaluations
- of the ODE at each step and will suffer from finite differences errors, but it is much simpler to implement from a user
- point of view.
- </p>
- <p>
- The parameters are identified by a name (a simple user defined string), which are also specified at <a
- href="../apidocs/org/apache/commons/math4/ode/JacobianMatrices.html">JacobianMatrices</a> class construction. If the ODE
- is simple enough that the user can implement df(t, y, p)/dp<sub>k</sub> directly for some of the parameters p<sub>k</sub>,
- then he can provide one or more classes implementing the <a
- href="../apidocs/org/apache/commons/math4/ode/ParameterJacobianProvider.html">ParameterJacobianProvider</a> interface by
- calling the JacobianMatrices.addParameterJacobianProvide method. The parameters are handled one at a time, but all the calls to
- ParameterJacobianProvider.computeParameterJacobian will be grouped in one sequence after the call to MainStateJacobianProvider.computeMainStateJacobian
- This feature can be used when all the derivatives share a lot of costly computation. In this case, the user
- is advised to compute all the needed derivatives at once during the call to computeMainStateJacobian, including the
- partial derivatives with respect to the parameters and to store the derivatives temporary. Then when the next calls to
- computeParameterJacobian will be triggerred, it will be sufficient to return the already computed derivatives. With this
- architecture, many computation can be saved. This of course implies that the classes implementing both interfaces know
- each other (they can even be the same class if desired, but it is not required). If the ODE is too complex or the user
- simply does not bother implementing df(t, y, p)/dp<sub>k</sub> directly for some k, then
- the JacobianMatrices.setParameterStep method should be called so finite differences are used to compute the derivatives
- for this parameter. It is possible to have some parameters for which derivatives are provided by a direct implementation
- while other parameters are computed using finite differences during the same integration.
- </p>
- <p>
- The following example corresponds to a simple case where all derivatives can be computed analytically. The state is
- a 2D point travelling along a circle. There are three parameters : the two coordinates of the center and the
- angular velocity.
- </p>
- <source>
-public class CircleODE implements MainStateJacobianProvider, ParameterJacobianProvider {
-
- public static final String CENTER_X = "cx";
- public static final String CENTER_Y = "cy";
- public static final String OMEGA = "omega";
-
- private double[] c;
- private double omega;
- private double[][] savedDfDp;
-
- public CircleODE(double[] c, double omega) {
- this.c = c;
- this.omega = omega;
- this.savedDfDp = new double[2][3];
- }
-
- public int getDimension() {
- return 2;
- }
-
- public void computeDerivatives(double t, double[] y, double[] yDot) {
- // the state is a 2D point, the ODE therefore corresponds to the velocity
- yDot[0] = omega * (c[1] - y[1]);
- yDot[1] = omega * (y[0] - c[0]);
- }
-
- public Collection<String> getParametersNames() {
- return Arrays.asList(CENTER_X, CENTER_Y, OMEGA);
- }
-
- public boolean isSupported(String name) {
- return CENTER_X.equals(name) || CENTER_Y.equals(name) || OMEGA.equals(name);
- }
-
- public void computeMainStateJacobian(double t, double[] y, double[] yDot, double[][] dFdY) {
-
- // compute the Jacobian of the main state
- dFdY[0][0] = 0;
- dFdY[0][1] = -omega;
- dFdY[1][0] = omega;
- dFdY[1][1] = 0;
-
- // precompute the derivatives with respect to the parameters,
- // they will be provided back when computeParameterJacobian are called later on
- savedDfDp[0][0] = 0;
- savedDfDp[0][1] = omega;
- savedDfDp[0][2] = c[1] - y[1];
- savedDfDp[1][0] = -omega;
- savedDfDp[1][1] = 0;
- savedDfDp[1][2] = y[0] - c[0];
-
- }
-
- public void computeParameterJacobian(double t, double[] y, double[] yDot,
- String paramName, double[] dFdP) {
- // we simply return the derivatives precomputed earlier
- if (CENTER_X.equals(paramName)) {
- dFdP[0] = savedDfDp[0][0];
- dFdP[1] = savedDfDp[1][0];
- } else if (CENTER_Y.equals(paramName)) {
- dFdP[0] = savedDfDp[0][1];
- dFdP[1] = savedDfDp[1][1];
- } else {
- dFdP[0] = savedDfDp[0][2];
- dFdP[1] = savedDfDp[1][2];
- }
- }
-
-}
- </source>
- <p>
- This ODE is integrated as follows:
- </p>
- <source>
- CircleODE circle = new CircleODE(new double[] {1.0, 1.0 }, 0.1);
-
- // here, we could select only a subset of the parameters, or use another order
- JacobianMatrices jm = new JacobianMatrices(circle, CircleODE.CENTER_X, CircleODE.CENTER_Y, CircleODE.OMEGA);
- jm.addParameterJacobianProvider(circle);
-
- ExpandableStatefulODE efode = new ExpandableStatefulODE(circle);
- efode.setTime(0);
- double[] y = { 1.0, 0.0 };
- efode.setPrimaryState(y);
-
- // create the variational equations and append them to the main equations, as secondary equations
- jm.registerVariationalEquations(efode);
-
- // integrate the compound state, with both main and additional equations
- DormandPrince853Integrator integrator = new DormandPrince853Integrator(1.0e-6, 1.0e3, 1.0e-10, 1.0e-12);
- integrator.setMaxEvaluations(5000);
- integrator.integrate(efode, 20.0);
-
- // retrieve the Jacobian of the final state with respect to initial state
- double[][] dYdY0 = new double[2][2];
- jm.getCurrentMainSetJacobian(dYdY0);
-
- // retrieve the Jacobians of the final state with resepct to the various parameters
- double[] dYdCx = new double[2];
- double[] dYdCy = new double[2];
- double[] dYdOm = new double[2];
- jm.getCurrentParameterJacobian(CircleODE.CENTER_X, dYdCx);
- jm.getCurrentParameterJacobian(CircleODE.CENTER_Y, dYdCy);
- jm.getCurrentParameterJacobian(CircleODE.OMEGA, dYdOm);
- </source>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/optimization.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/optimization.xml b/src/site/xdoc/userguide/optimization.xml
deleted file mode 100644
index 98f434a..0000000
--- a/src/site/xdoc/userguide/optimization.xml
+++ /dev/null
@@ -1,591 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="optimization.html">
-
- <properties>
- <title>The Commons Math User Guide - Optimization</title>
- </properties>
-
- <body>
- <section name="12 Optimization">
- <p><em>The contents of this section currently describes deprecated classes.</em>
- Please refer to the new <a href="../apidocs/org/apache/commons/math4/optim/package-summary.html">API
- description</a>.
- </p>
- <p>Least squares optimizers are not in this package anymore, they have been moved
- in a dedicated least-squares sub-package described in the <a href="./leastsquares.html">least squares</a>
- section.
- </p>
-
- <subsection name="12.1 Overview" href="overview">
- <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/math4/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/math4/optimization/univariate/UnivariateOptimizer.html">
- UnivariateOptimizer</a> for <a
- href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">
- univariate real functions</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/optimization/MultivariateOptimizer.html">
- MultivariateOptimizer</a> for <a
- href="../apidocs/org/apache/commons/math4/analysis/MultivariateFunction.html">
- multivariate real functions</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/optimization/DifferentiableMultivariateOptimizer.html">
- DifferentiableMultivariateOptimizer</a> for <a
- href="../apidocs/org/apache/commons/math4/analysis/DifferentiableMultivariateFunction.html">
- differentiable multivariate real functions</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/optimization/DifferentiableMultivariateVectorOptimizer.html">
- DifferentiableMultivariateVectorOptimizer</a> for <a
- href="../apidocs/org/apache/commons/math4/analysis/DifferentiableMultivariateVectorFunction.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/math4/analysis/MultivariateVectorFunction.html">
- non-differentiable multivariate vectorial function</a> by converting it to a <a
- href="../apidocs/org/apache/commons/math4/analysis/MultivariateFunction.html">
- non-differentiable multivariate real function</a> thanks to the <a
- href="../apidocs/org/apache/commons/math4/optimization/LeastSquaresConverter.html">
- LeastSquaresConverter</a> helper class. The transformed function can be optimized using
- any implementation of the <a
- href="../apidocs/org/apache/commons/math4/optimization/MultivariateOptimizer.html">
- MultivariateOptimizer</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>
- </subsection>
- <subsection name="12.2 Univariate Functions" href="univariate">
- <p>
- A <a href="../apidocs/org/apache/commons/math4/optimization/univariate/UnivariateOptimizer.html">
- UnivariateOptimizer</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>
- </subsection>
- <subsection name="12.3 Linear Programming" href="linear">
- <p>
- This package provides an implementation of George Dantzig's simplex algorithm
- for solving linear optimization problems with linear equality and inequality
- constraints.
- </p>
- </subsection>
- <subsection name="12.4 Direct Methods" href="direct">
- <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">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 four solvers:
- <ul>
- <li>the classical <a
- href="../apidocs/org/apache/commons/math4/optimization/direct/NelderMeadSimplex.html">
- Nelder-Mead</a> method,</li>
- <li>Virginia Torczon's <a
- href="../apidocs/org/apache/commons/math4/optimization/direct/MultiDirectionalSimplex.html">
- multi-directional</a> method,</li>
- <li>Nikolaus Hansen's <a
- href="../apidocs/org/apache/commons/math4/optimization/direct/CMAESOptimizer.html">
- </a>Covariance Matrix Adaptation Evolution Strategy (CMA-ES),</li>
- <li>Mike Powell's <a
- href="../apidocs/org/apache/commons/math4/optimization/direct/BOBYQAOptimizer.html">
- BOBYQA</a> method.
- </li>
- </ul>
- </p>
- <p>
- The first two simplex-based methods do not handle simple bounds constraints by themselves.
- However there are two adapters(<a
- href="../apidocs/org/apache/commons/math4/optimization/direct/MultivariateFunctionMappingAdapter.html">
- MultivariateFunctionMappingAdapter</a> and <a
- href="../apidocs/org/apache/commons/math4/optimization/direct/MultivariateFunctionPenaltyAdapter.html">
- MultivariateFunctionPenaltyAdapter</a>) that can be used to wrap the user function in
- such a way the wrapped function is unbounded and can be used with these optimizers, despite
- the fact the underlying function is still bounded and will be called only with feasible
- points that fulfill the constraints. Note however that using these adapters are only a
- poor man solutions to simple bounds optimization constraints. Better solutions are to use an
- optimizer that directly supports simple bounds. Some caveats of the mapping adapter
- solution are that
- <ul>
- <li>behavior near the bounds may be numerically unstable as bounds are mapped from
- infinite values,</li>
- <li>start value is evaluated by the optimizer as an unbounded variable,
- so it must be converted from bounded to unbounded by user,</li>
- <li>optimum result is evaluated by the optimizer as an unbounded variable,
- so it must be converted from unbounded to bounded by user,</li>
- <li>convergence values are evaluated by the optimizer as unbounded variables,
- so there will be scales differences when converted to bounded variables,</li>
- <li>in the case of simplex based solvers, the initial simplex should be set up
- as delta in unbounded variables.</li>
- </ul>
- One caveat of penalty adapter is that if start point or start simplex is outside of the allowed
- range, only the penalty function is used, and the optimizer may converge without ever entering
- the allowed range.
- </p>
- <p>
- The last methods do handle simple bounds constraints directly, so the adapters are not needed
- with them.
- </p>
- </subsection>
- <subsection name="12.5 General Case" href="general">
- <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/math4/optimization/general/GaussNewtonOptimizer.html">
- Gauss-Newton</a> method. The second one is the <a
- href="../apidocs/org/apache/commons/math4/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/math4/analysis/DifferentiableMultivariateVectorFunction.html">
- DifferentiableMultivariateVectorFunction</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>
-
- <dl>
- <dt>Quadratic Problem Example</dt>
- <dd>
-
-
- We are looking to find the best parameters [a, b, c] for the quadratic function
- <b><code>f(x) = a x<sup>2</sup> + b x + c</code></b>.
- The data set below was generated using [a = 8, b = 10, c = 16].
- A random number between zero and one was added to each y value calculated.
-
- <table cellspacing="0" cellpadding="3">
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;"><b>X</b></td>
-<td valign="bottom" align="center" style=" font-size:10pt;"><b>Y</b></td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">34.234064369</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">2</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">68.2681162306108</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">3</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">118.615899084602</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">4</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">184.138197238557</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">5</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">266.599877916276</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">6</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">364.147735251579</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">7</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">478.019226091914</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">8</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">608.140949270688</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">9</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">754.598868667148</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">10</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">916.128818085883</td>
-</tr>
-</table>
-
-<p>
-First we need to implement the interface <a href="../apidocs/org/apache/commons/math4/analysis/DifferentiableMultivariateVectorFunction.html">DifferentiableMultivariateVectorFunction</a>.
-This requires the implementation of the method signatures:
-</p>
-
-
-<ul>
-<li><b>MultivariateMatrixFunction jacobian()</b></li>
-<li><b>double[] value(double[] point)</b></li>
-</ul>
-
-<p>
-We'll tackle the implementation of the <code>MultivariateMatrixFunction jacobian()</code> method first. You may wish to familiarize yourself with what a <a href="http://en.wikipedia.org/wiki/Jacobian_matrix_and_determinant"> Jacobian Matrix</a> is.
-In this case the Jacobian is the partial derivative of the function with respect
-to the parameters a, b and c. These derivatives are computed as follows:
-<ul>
- <li>d(ax<sup>2</sup> + bx + c)/da = x<sup>2</sup></li>
- <li>d(ax<sup>2</sup> + bx + c)/db = x</li>
- <li>d(ax<sup>2</sup> + bx + c)/dc = 1</li>
-</ul>
-</p>
-
-<p>
-For a quadratic which has three variables the Jacobian Matrix will have three columns, one for each variable, and the number
-of rows will equal the number of rows in our data set, which in this case is ten. So for example for <tt>[a = 1, b = 1, c = 1]</tt>, the Jacobian Matrix is (excluding the first column which shows the value of x):
-</p>
-
-<table cellspacing="0" cellpadding="3">
-<tr>
-<td valign="bottom" align="left" style=" font-size:10pt;"><b>x</b></td>
-<td valign="bottom" align="left" style=" font-size:10pt;"><b>d(ax<sup>2</sup> + bx + c)/da</b></td>
-<td valign="bottom" align="left" style=" font-size:10pt;"><b>d(ax<sup>2</sup> + bx + c)/db</b></td>
-<td valign="bottom" align="left" style=" font-size:10pt;"><b>d(ax<sup>2</sup> + bx + c)/dc</b></td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">2</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">4</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">2</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">3</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">9</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">3</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">4</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">16</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">4</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">5</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">25</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">5</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">6</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">36</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">6</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">7</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">49</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">7</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">8</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">64</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">8</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">9</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">81</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">9</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-<tr>
-<td valign="bottom" align="center" style=" font-size:10pt;">10</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">100</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">10</td>
-<td valign="bottom" align="center" style=" font-size:10pt;">1</td>
-</tr>
-</table>
-
-<p>
-The implementation of the <code>MultivariateMatrixFunction jacobian()</code> for this problem looks like this (The <code>x</code>
-parameter is an ArrayList containing the independent values of the data set):
-</p>
-
-<source>
- private double[][] jacobian(double[] variables) {
- double[][] jacobian = new double[x.size()][3];
- for (int i = 0; i < jacobian.length; ++i) {
- jacobian[i][0] = x.get(i) * x.get(i);
- jacobian[i][1] = x.get(i);
- jacobian[i][2] = 1.0;
- }
- return jacobian;
- }
-
- public MultivariateMatrixFunction jacobian() {
- return new MultivariateMatrixFunction() {
- private static final long serialVersionUID = -8673650298627399464L;
- public double[][] value(double[] point) {
- return jacobian(point);
- }
- };
- }
-</source>
-
-<p>
-Note that if for some reason the derivative of the objective function with respect
-to its variables is difficult to obtain,
-<a href="http://en.wikipedia.org/wiki/Numerical_differentiation">Numerical differentiation</a> can be used.
-</p>
-
-
-<p>
-The implementation of the <code>double[] value(double[] point)</code> method, which returns
- a <code>double</code> array containing the
-values the objective function returns per given independent value
-and the current set of variables or parameters,
-can be seen below:
-</p>
-
-<source>
- public double[] value(double[] variables) {
- double[] values = new double[x.size()];
- for (int i = 0; i < values.length; ++i) {
- values[i] = (variables[0] * x.get(i) + variables[1]) * x.get(i) + variables[2];
- }
- return values;
- }
-</source>
-
-<p>
-Below is the the class containing all the implementation details
-(Taken from the Apache Commons Math <b>org.apache.commons.complex.optimization.general.LevenbergMarquardtOptimizerTest</b>):
-</p>
-
-<source>
-private static class QuadraticProblem
- implements DifferentiableMultivariateVectorFunction, Serializable {
-
- private static final long serialVersionUID = 7072187082052755854L;
- private List<Double> x;
- private List<Double> y;
-
- public QuadraticProblem() {
- x = new ArrayList<Double>();
- y = new ArrayList<Double>();
- }
-
- public void addPoint(double x, double y) {
- this.x.add(x);
- this.y.add(y);
- }
-
- public double[] calculateTarget() {
- double[] target = new double[y.size()];
- for (int i = 0; i < y.size(); i++) {
- target[i] = y.get(i).doubleValue();
- }
- return target;
- }
-
- private double[][] jacobian(double[] variables) {
- double[][] jacobian = new double[x.size()][3];
- for (int i = 0; i < jacobian.length; ++i) {
- jacobian[i][0] = x.get(i) * x.get(i);
- jacobian[i][1] = x.get(i);
- jacobian[i][2] = 1.0;
- }
- return jacobian;
- }
-
- public double[] value(double[] variables) {
- double[] values = new double[x.size()];
- for (int i = 0; i < values.length; ++i) {
- values[i] = (variables[0] * x.get(i) + variables[1]) * x.get(i) + variables[2];
- }
- return values;
- }
-
- public MultivariateMatrixFunction jacobian() {
- return new MultivariateMatrixFunction() {
- private static final long serialVersionUID = -8673650298627399464L;
- public double[][] value(double[] point) {
- return jacobian(point);
- }
- };
- }
-}
-</source>
-
-<p>
-The below code shows how to go about using the above class
-and a LevenbergMarquardtOptimizer instance to produce an
-optimal set of quadratic curve fitting parameters:
-</p>
-
- <source>
- QuadraticProblem problem = new QuadraticProblem();
-
- problem.addPoint(1, 34.234064369);
- problem.addPoint(2, 68.2681162306);
- problem.addPoint(3, 118.6158990846);
- problem.addPoint(4, 184.1381972386);
- problem.addPoint(5, 266.5998779163);
- problem.addPoint(6, 364.1477352516);
- problem.addPoint(7, 478.0192260919);
- problem.addPoint(8, 608.1409492707);
- problem.addPoint(9, 754.5988686671);
- problem.addPoint(10, 916.1288180859);
-
- LevenbergMarquardtOptimizer optimizer = new LevenbergMarquardtOptimizer();
-
- final double[] weights = { 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 };
-
- final double[] initialSolution = {1, 1, 1};
-
- PointVectorValuePair optimum = optimizer.optimize(100,
- problem,
- problem.calculateTarget(),
- weights,
- initialSolution);
-
- final double[] optimalValues = optimum.getPoint();
-
- System.out.println("A: " + optimalValues[0]);
- System.out.println("B: " + optimalValues[1]);
- System.out.println("C: " + optimalValues[2]);
-
- </source>
-
-<p>
-If you run the above sample you will see
-the following printed by the console:
-</p>
-
-<pre>
-A: 7.998832172372726
-B: 10.001841530162448
-C: 16.324008168386605
-</pre>
-
- </dd></dl>
- <p>
- In addition to least squares solving, the <a
- href="../apidocs/org/apache/commons/math4/optimization/general/NonLinearConjugateGradientOptimizer.html">
- NonLinearConjugateGradientOptimizer</a> class provides a non-linear conjugate gradient algorithm
- to optimize <a
- href="../apidocs/org/apache/commons/math4/analysis/DifferentiableMultivariateFunction.html">
- DifferentiableMultivariateFunction</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>
- <p>
- The <a href="../apidocs/org/apache/commons/math4/optimization/direct/PowellOptimizer.html">
- PowellOptimizer</a> provides an optimization method for non-differentiable functions.
- </p>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/overview.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/overview.xml b/src/site/xdoc/userguide/overview.xml
deleted file mode 100644
index 9c97cd6..0000000
--- a/src/site/xdoc/userguide/overview.xml
+++ /dev/null
@@ -1,157 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document>
- <properties>
- <title>User Guide - Overview</title>
- </properties>
-
-<body>
-
-<section name="Overview">
-
-<subsection name="0.1 About The User Guide" href="about">
- <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>
-</subsection>
-
-<subsection name="0.2 What's in commons-math" href="summary">
- <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>Fitting a curve to a set of data points</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">commons-dev mailing list</a> with
- [math] at the beginning of the subject line.
- </p>
-</subsection>
-
-<subsection name="0.3 How commons-math is organized" href="organization">
- <p>
- Commons Math is divided into sixteen subpackages, based on functionality provided.
- <ul>
- <li><a href="stat.html">org.apache.commons.complex.stat</a> - statistics, statistical tests</li>
- <li><a href="analysis.html">org.apache.commons.complex.analysis</a> - rootfinding, integration, interpolation, polynomials</li>
- <li><a href="random.html">org.apache.commons.complex.random</a> - random numbers, strings and data generation</li>
- <li><a href="special.html">org.apache.commons.complex.special</a> - special functions (Gamma, Beta) </li>
- <li><a href="linear.html">org.apache.commons.complex.linear</a> - matrices, solving linear systems </li>
- <li><a href="utilities.html">org.apache.commons.complex.util</a> - common math/stat functions extending java.lang.Math </li>
- <li><a href="complex.html">org.apache.commons.complex.complex</a> - complex numbers</li>
- <li><a href="distribution.html">org.apache.commons.complex.distribution</a> - probability distributions</li>
- <li><a href="fraction.html">org.apache.commons.complex.fraction</a> - rational numbers</li>
- <li><a href="transform.html">org.apache.commons.complex.transform</a> - transform methods (Fast Fourier)</li>
- <li><a href="geometry.html">org.apache.commons.complex.geometry</a> - geometry (Euclidean spaces and Binary Space Partitioning)</li>
- <li><a href="optimization.html">org.apache.commons.complex.optim</a> - function maximization or minimization</li>
- <li><a href="ode.html">org.apache.commons.complex.ode</a> - Ordinary Differential Equations integration</li>
- <li><a href="genetics.html">org.apache.commons.complex.genetics</a> - Genetic Algorithms</li>
- <li><a href="fitting.html">org.apache.commons.complex.fitting</a> - Curve Fitting</li>
- <li><a href="ml.html">org.apache.commons.complex.ml</a> - Machine Learning</li>
- </ul>
- Package javadocs are <a href="../apidocs/index.html">here</a>
- </p>
-</subsection>
-
-<subsection name="0.4 How interface contracts are specified in commons-math javadoc" href="contracts">
- <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, a
- <a href="../apidocs/org/apache/commons/math4/exception/MathIllegalArgumentException.html">
- MathIllegalArgumentException</a> or
- <a href="../apidocs/org/apache/commons/math4/exception/MathIllegalStateException.html">
- MathIllegalStateException</a> 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/">
- IEEE 754 standard</a> for floating point arithmetic and with java.lang.Math, Commons Math
- methods return <code>Double.NaN</code> values. Conditions under which <code>Double.NaN</code>
- or other special values are returned are fully specified in the javadoc method comments.
- </p>
- <p>
- As of version 2.2, the policy for dealing with null references is as
- follows: When an argument is unexpectedly null, a
- <a href="../apidocs/org/apache/commons/math4/exception/NullArgumentException.html">
- NullArgumentException</a> is raised to signal the illegal argument. Note that this
- class does not inherit from the standard <code>NullPointerException</code> but is a subclass
- of <code>MathIllegalArgumentException</code>.
- </p>
-</subsection>
-
-<subsection name="0.5 Dependencies" href="dependencies">
- <p>
- Commons Math requires JDK 1.5+ and has no runtime dependencies.
- </p>
-</subsection>
-
-<subsection name="0.6 License" href="license">
- <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"/>.
- </p>
-
- <p>
- This product includes software developed by other third parties and
- distributed under licenses terms compatible with Apache License, Version 2.0.
- All the licenses of such third parties products are available in the distribution
- in the LICENSE.txt file. Some products require additional attribution, these
- attributions can be found in the NOTICE.txt file. These files are available
- both in the source packages and in the binaries distribution jar files.
- </p>
-
-</subsection>
-
-</section>
-
-</body>
-</document>
-
[5/5] commons-numbers git commit: NUMBERS-70: Delete files describing
"Commons Math" (userguide).
Posted by er...@apache.org.
NUMBERS-70: Delete files describing "Commons Math" (userguide).
Project: http://git-wip-us.apache.org/repos/asf/commons-numbers/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-numbers/commit/b36e21d9
Tree: http://git-wip-us.apache.org/repos/asf/commons-numbers/tree/b36e21d9
Diff: http://git-wip-us.apache.org/repos/asf/commons-numbers/diff/b36e21d9
Branch: refs/heads/master
Commit: b36e21d9ad3f89aa4d75eca52158ec9c7196a511
Parents: fff2494
Author: Gilles Sadowski <gi...@harfang.homelinux.org>
Authored: Tue Sep 4 00:31:47 2018 +0200
Committer: Gilles Sadowski <gi...@harfang.homelinux.org>
Committed: Tue Sep 4 00:31:47 2018 +0200
----------------------------------------------------------------------
src/site/xdoc/userguide/analysis.xml | 754 ---------------
src/site/xdoc/userguide/complex.xml | 145 ---
src/site/xdoc/userguide/core.xml | 39 +
src/site/xdoc/userguide/distribution.xml | 117 ---
src/site/xdoc/userguide/exceptions.xml | 119 ---
src/site/xdoc/userguide/filter.xml | 226 -----
src/site/xdoc/userguide/fitting.xml | 144 ---
src/site/xdoc/userguide/fraction.xml | 109 ---
src/site/xdoc/userguide/genetics.xml | 134 ---
src/site/xdoc/userguide/geometry.xml | 338 -------
src/site/xdoc/userguide/index.xml | 167 +---
src/site/xdoc/userguide/leastsquares.xml | 366 --------
src/site/xdoc/userguide/linear.xml | 212 -----
src/site/xdoc/userguide/ml.xml | 146 ---
src/site/xdoc/userguide/ode.xml | 491 ----------
src/site/xdoc/userguide/optimization.xml | 591 ------------
src/site/xdoc/userguide/overview.xml | 157 ----
src/site/xdoc/userguide/random.xml | 563 -----------
src/site/xdoc/userguide/stat.xml | 1246 -------------------------
src/site/xdoc/userguide/transform.xml | 45 -
src/site/xdoc/userguide/utilities.xml | 246 -----
21 files changed, 45 insertions(+), 6310 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/analysis.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/analysis.xml b/src/site/xdoc/userguide/analysis.xml
deleted file mode 100644
index 9782741..0000000
--- a/src/site/xdoc/userguide/analysis.xml
+++ /dev/null
@@ -1,754 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="analysis.html">
- <properties>
- <title>The Commons Math User Guide - Numerical Analysis</title>
- </properties>
- <body>
- <section name="4 Numerical Analysis">
- <subsection name="4.1 Overview" href="overview">
- <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, interpolation and differentiation.
- 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>
- </subsection>
- <subsection name="4.2 Error handling" href="errorhandling">
- <p>
- For user-defined functions, when the method encounters an error
- during evaluation, users must use their <em>own</em> unchecked exceptions.
- The following example shows the recommended way to do that, using root
- solving as the example (the same construct should be used for ODE
- integrators or for optimizations).
- </p>
- <source>private static class LocalException extends RuntimeException {
-
- // the x value that caused the problem
- private final double x;
-
- public LocalException(double x) {
- this.x = x;
- }
-
- public double getX() {
- return x;
- }
-
- }
-
- private static class MyFunction implements UnivariateFunction {
- public double value(double x) {
- double y = hugeFormula(x);
- if (somethingBadHappens) {
- throw new LocalException(x);
- }
- return y;
- }
- }
-
- public void compute() {
- try {
- solver.solve(maxEval, new MyFunction(a, b, c), min, max);
- } catch (LocalException le) {
- // retrieve the x value
- }
- }
- </source>
- <p>
- As shown in this example the exception is really something local to user code
- and there is a guarantee Apache Commons Math will not mess with it.
- The user is safe.
- </p>
- </subsection>
- <subsection name="4.3 Root-finding" href="rootfinding">
- <p>
- <a href="../apidocs/org/apache/commons/math4/analysis/solvers/UnivariateSolver.html">
- UnivariateSolver</a>, <a href="../apidocs/org/apache/commons/math4/analysis/solvers/UnivariateDifferentiableSolver.html">
- UnivariateDifferentiableSolver</a> and <a href="../apidocs/org/apache/commons/math4/analysis/solvers/PolynomialSolver.html">
- PolynomialSolver</a> provide means to find roots of
- <a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a>,
- <a href="../apidocs/org/apache/commons/math4/analysis/differentiation/UnivariateDifferentiable.html">differentiable univariate real-valued functions</a>,
- and <a href="../apidocs/org/apache/commons/math4/analysis/polynomials/PolynomialFunction.html">polynomial functions</a> respectively.
- A root is the value where the function takes the value 0. Commons-Math
- includes implementations of the several root-finding algorithms:
- </p>
- <table border="1" align="center">
- <tr BGCOLOR="#CCCCFF"><td colspan="5"><font size="+1">Root solvers</font></td></tr>
- <tr BGCOLOR="#EEEEFF"><font size="+1"><td>Name</td><td>Function type</td><td>Convergence</td><td>Needs initial bracketing</td><td>Bracket side selection</td></font></tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/BisectionSolver.html">Bisection</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>linear, guaranteed</td>
- <td>yes</td>
- <td>yes</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/BrentSolver.html">Brent-Dekker</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>super-linear, guaranteed</td>
- <td>yes</td>
- <td>no</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/BracketingNthOrderBrentSolver.html">bracketing n<sup>th</sup> order Brent</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>variable order, guaranteed</td>
- <td>yes</td>
- <td>yes</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/IllinoisSolver.html">Illinois Method</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>super-linear, guaranteed</td>
- <td>yes</td>
- <td>yes</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/LaguerreSolver.html">Laguerre's Method</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/polynomials/PolynomialFunction.html">polynomial functions</a></td>
- <td>cubic for simple root, linear for multiple root</td>
- <td>yes</td>
- <td>no</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/MullerSolver.html">Muller's Method</a> using bracketing to deal with real-valued functions</td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>quadratic close to roots</td>
- <td>yes</td>
- <td>no</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/MullerSolver2.html">Muller's Method</a> using modulus to deal with real-valued functions</td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>quadratic close to root</td>
- <td>yes</td>
- <td>no</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/NewtonRaphsonSolver.html">Newton-Raphson's Method</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/differentiation/UnivariateDifferentiableFunction.html">differentiable univariate real-valued functions</a></td>
- <td>quadratic, non-guaranteed</td>
- <td>no</td>
- <td>no</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/PegasusSolver.html">Pegasus Method</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>super-linear, guaranteed</td>
- <td>yes</td>
- <td>yes</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/RegulaFalsiSolver.html">Regula Falsi (false position) Method</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>linear, guaranteed</td>
- <td>yes</td>
- <td>yes</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/RiddersSolver.html">Ridder's Method</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>super-linear</td>
- <td>yes</td>
- <td>no</td>
- </tr>
- <tr>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/solvers/SecantSolver.html">Secant Method</a></td>
- <td><a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">univariate real-valued functions</a></td>
- <td>super-linear, non-guaranteed</td>
- <td>yes</td>
- <td>no</td>
- </tr>
- </table>
- <p>
- Some algorithms require that the initial search interval brackets the root
- (i.e. the function values at interval end points have opposite signs). Some
- algorithms preserve bracketing throughout computation and allow user to
- specify which side of the convergence interval to select as the root. It is
- also possible to force a side selection after a root has been found even
- for algorithms that do not provide this feature by themselves. This is
- useful for example in sequential search, for which a new search interval is
- started after a root has been found in order to find the next root. In this
- case, user must select a side to ensure his loop is not stuck on one root
- and always return the same solution without making any progress.
- </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 by calling its constructor, often providing relative and absolute
- accuracy. Using a solver object, roots of functions
- are easily found using the <code>solve</code> methods. These methods takes
- a maximum iteration count <code>maxEval</code>, a function <code>f</code>,
- and either two domain values, <code>min</code> and <code>max</code>, or a
- <code>startValue</code> as parameters. If the maximal number of iterations
- count is exceeded, non-convergence is assumed and a <code>ConvergenceException</code>
- exception is thrown. A suggested 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.
- <a
- href="../apidocs/org/apache/commons/math4/analysis/solvers/BracketedUnivariateSolver.html">Bracketed
- solvers</a> also take an <a
- href="../apidocs/org/apache/commons/math4/analysis/solvers/AllowedSolution.html">allowed solution</a>
- enum parameter to specify which side of the final convergence interval should be
- selected as the root. It can be <code>ANY_SIDE</code>, <code>LEFT_SIDE</code>, <code>RIGHT_SIDE</code>,
- <code>BELOW_SIDE</code> or <code>ABOVE_SIDE</code>. Left and right are used to specify the root along
- the function parameter axis while below and above refer to the function value axis. The solve methods
- compute 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> (except for the secant method, which may find a solution outside the interval)</li>
- </ul>
- </p>
- <p>
- Typical usage:
- </p>
- <source>UnivariateFunction function = // some user defined function object
-final double relativeAccuracy = 1.0e-12;
-final double absoluteAccuracy = 1.0e-8;
-final int maxOrder = 5;
-UnivariateSolver solver = new BracketingNthOrderBrentSolver(relativeAccuracy, absoluteAccuracy, maxOrder);
-double c = solver.solve(100, function, 1.0, 5.0, AllowedSolution.LEFT_SIDE);</source>
- <p>
- Force bracketing, by refining a base solution found by a non-bracketing solver:
- </p>
- <source>UnivariateFunction function = // some user defined function object
-final double relativeAccuracy = 1.0e-12;
-final double absoluteAccuracy = 1.0e-8;
-UnivariateSolver nonBracketing = new BrentSolver(relativeAccuracy, absoluteAccuracy);
-double baseRoot = nonBracketing.solve(100, function, 1.0, 5.0);
-double c = UnivariateSolverUtils.forceSide(100, function,
- new PegasusSolver(relativeAccuracy, absoluteAccuracy),
- baseRoot, 1.0, 5.0, AllowedSolution.LEFT_SIDE);
-</source>
- <p>
- The <code>BrentSolver</code> uses the Brent-Dekker algorithm which is
- fast and robust. 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>BracketingNthOrderBrentSolver</code> uses an extension of the
- Brent-Dekker algorithm which uses inverse n<sup>th</sup> order polynomial
- interpolation instead of inverse quadratic interpolation, and which allows
- selection of the side of the convergence interval for result bracketing.
- This is now the recommended algorithm for most users since it has the
- largest order, doesn't require derivatives, has guaranteed convergence
- and allows result bracket selection.
- </p>
- <p>
- The <code>SecantSolver</code> uses a straightforward secant
- algorithm which does not bracket the search and therefore does not
- guarantee convergence. It may be faster than Brent on some well-behaved
- functions.
- </p>
- <p>
- The <code>RegulaFalsiSolver</code> is variation of secant preserving
- bracketing, but then it may be slow, as one end point of the search interval
- will become fixed after and only the other end point will converge to the root,
- hence resulting in a search interval size that does not decrease to zero.
- </p>
- <p>
- The <code>IllinoisSolver</code> and <code>PegasusSolver</code> are
- well-known variations of regula falsi that fix the problem of stuck
- end points by slightly weighting one endpoint to balance the interval
- at next iteration. Pegasus is often faster than Illinois. Pegasus may
- be the algorithm of choice for selecting a specific side of the convergence
- interval.
- </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>UnivariateSolver</code> interface exposes many
- properties to control the convergence of a solver. The accuracy properties
- are set at solver instance creation and cannot be changed afterwards,
- there are only getters to retriveve their values, no setters are available.
- <table>
- <tr><th>Property</th><th>Purpose</th></tr>
- <tr>
- <td>Absolute accuracy</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>
- <td>Relative accuracy</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>
- <td>Function value accuracy</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>
- </table>
- </p>
- </subsection>
- <subsection name="4.4 Interpolation" href="interpolation">
- <p>
- A <a href="../apidocs/org/apache/commons/math4/analysis/interpolation/UnivariateInterpolator.html">
- UnivariateInterpolator</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/math4/analysis/UnivariateFunction.html">
- UnivariateFunction</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>
- <source>double x[] = { 0.0, 1.0, 2.0 };
-double y[] = { 1.0, -1.0, 2.0};
-UnivariateInterpolator interpolator = new SplineInterpolator();
-UnivariateFunction function = interpolator.interpolate(x, y);
-double interpolationX = 0.5;
-double interpolatedY = function.value(x);
-System.out println("f(" + interpolationX + ") = " + interpolatedY);</source>
- <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">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">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">MS thesis</a>.
- </p>
- <p>
- <a href="http://en.wikipedia.org/wiki/Hermite_interpolation">Hermite interpolation</a>
- is an interpolation method that can use derivatives in addition to function values at sample points. The <a
- href="../apidocs/org/apache/commons/math4/analysis/interpolation/HermiteInterpolator.html">HermiteInterpolator</a>
- class implements this method for vector-valued functions. The sampling points can have any spacing (there are
- no requirements for a regular grid) and some points may provide derivatives while others don't provide them
- (or provide derivatives to a smaller order). Points are added one at a time, as shown in the following example:
- </p>
- <source>HermiteInterpolator interpolator = new HermiteInterpolator;
-// at x = 0, we provide both value and first derivative
-interpolator.addSamplePoint(0.0, new double[] { 1.0 }, new double[] { 2.0 });
-// at x = 1, we provide only function value
-interpolator.addSamplePoint(1.0, new double[] { 4.0 });
-// at x = 2, we provide both value and first derivative
-interpolator.addSamplePoint(2.0, new double[] { 5.0 }, new double[] { 2.0 });
-// should print "value at x = 0.5: 2.5625"
-System.out.println("value at x = 0.5: " + interpolator.value(0.5)[0]);
-// should print "derivative at x = 0.5: 3.5"
-System.out.println("derivative at x = 0.5: " + interpolator.derivative(0.5)[0]);
-// should print "interpolation polynomial: 1 + 2 x + 4 x^2 - 4 x^3 + x^4"
-System.out.println("interpolation polynomial: " + interpolator.getPolynomials()[0]);</source>
- <p>
- A <a href="../apidocs/org/apache/commons/math4/analysis/interpolation/BivariateGridInterpolator.html">
- BivariateGridInterpolator</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>f<sub>ij</sub></code>)
- yields <code>f(x<sub>i</sub>,y<sub>j</sub>)=f<sub>ij</sub></code> to the best accuracy
- possible. The result is provided as an object implementing the
- <a href="../apidocs/org/apache/commons/math4/analysis/BivariateFunction.html">
- BivariateFunction</a> interface. It can therefore be evaluated at any point,
- including a point not belonging to the original set.
- The arrays <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 grid.
- </p>
- <p>
- In <a href="http://en.wikipedia.org/wiki/Bicubic_interpolation">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 grid, as well as the values of the
- partial derivatives of the function at those grid points.
- From two-dimensional data sampled on a grid, the
- <a href="../apidocs/org/apache/commons/math4/analysis/interpolation/BicubicSplineInterpolator.html">
- BicubicSplineInterpolator</a> computes a
- <a href="../apidocs/org/apache/commons/math4/analysis/interpolation/BicubicSplineInterpolatingFunction.html">
- bicubic interpolating function</a>.
- Prior to computing an interpolating function, the
- <a href="../apidocs/org/apache/commons/math4/analysis/interpolation/SmoothingPolynomialBicubicSplineInterpolator.html">
- SmoothingPolynomialBicubicSplineInterpolator</a> class performs smoothing of
- the data by computing the polynomial that best fits each of the one-dimensional
- curves along each of the coordinate axes.
- </p>
- <p>
- A <a href="../apidocs/org/apache/commons/math4/analysis/interpolation/TrivariateGridInterpolator.html">
- TrivariateGridInterpolator</a> is used to find a trivariate 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>k</sub></code>,
- <code>f<sub>ijk</sub></code>)
- yields <code>f(x<sub>i</sub>,y<sub>j</sub>,z<sub>k</sub>)=f<sub>ijk</sub></code>
- to the best accuracy possible. The result is provided as an object implementing the
- <a href="../apidocs/org/apache/commons/math4/analysis/TrivariateFunction.html">
- TrivariateFunction</a> interface. It can therefore be evaluated at any point,
- including a point not belonging to the original set.
- The arrays <code>x<sub>i</sub></code>, <code>y<sub>j</sub></code> and
- <code>z<sub>k</sub></code> must be sorted in increasing order in order to define
- a three-dimensional grid.
- </p>
- <p>
- In <a href="http://en.wikipedia.org/wiki/Tricubic_interpolation">tricubic interpolation</a>,
- the interpolation function is a 3rd-degree polynomial of three variables. The coefficients
- are computed from the function values sampled on a grid, as well as the values of the
- partial derivatives of the function at those grid points.
- From three-dimensional data sampled on a grid, the
- <a href="../apidocs/org/apache/commons/math4/analysis/interpolation/TricubicSplineInterpolator.html">
- TricubicSplineInterpolator</a> computes a
- <a href="../apidocs/org/apache/commons/math4/analysis/interpolation/TricubicSplineInterpolatingFunction.html">
- tricubic interpolating function</a>.
- </p>
- </subsection>
- <subsection name="4.5 Integration" href="integration">
- <p>
- A <a href="../apidocs/org/apache/commons/math4/analysis/integration/UnivariateIntegrator.html">
- UnivariateIntegrator</a> provides the means to numerically integrate
- <a href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">
- univariate real-valued functions</a>.
- Commons-Math includes implementations of the following integration algorithms: <ul>
- <li><a href="../apidocs/org/apache/commons/math4/analysis/integration/RombergIntegrator.html">
- Romberg's method</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/analysis/integration/SimpsonIntegrator.html">
- Simpson's method</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/analysis/integration/TrapezoidIntegrator.html">
- trapezoid method</a></li>
- <li><a href="../apidocs/org/apache/commons/math4/analysis/integration/LegendreGaussIntegrator.html">
- Legendre-Gauss method</a></li>
- </ul>
- </p>
- </subsection>
- <subsection name="4.6 Polynomials" href="polynomials">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/analysis/polynomials/package-summary.html">
- org.apache.commons.complex.analysis.polynomials</a> package provides real
- coefficients polynomials.
- </p>
- <p>
- The <a href="../apidocs/org/apache/commons/math4/analysis/polynomials/PolynomialFunction.html">
- PolynomialFunction</a> class is the most general one, using traditional
- coefficients arrays. The
- <a href="../apidocs/org/apache/commons/math4/analysis/polynomials/PolynomialsUtils.html">
- PolynomialsUtils</a> utility class provides static factory methods to build
- Chebyshev, Hermite, Jacobi, Laguerre and Legendre polynomials. Coefficients are
- computed using exact fractions so these factory methods can build polynomials
- up to any degree.
- </p>
- </subsection>
- <subsection name="4.7 Differentiation" href="differentiation">
- <p>
- The <a href="../apidocs/org/apache/commons/math4/analysis/differentiation/package-summary.html">
- org.apache.commons.complex.analysis.differentiation</a> package provides a general-purpose
- differentiation framework.
- </p>
- <p>
- The core class is <a href="../apidocs/org/apache/commons/math4/analysis/differentiation/DerivativeStructure.html">
- DerivativeStructure</a> which holds the value and the differentials of a function. This class
- handles some arbitrary number of free parameters and arbitrary derivation order. It is used
- both as the input and the output type for the <a
- href="../apidocs/org/apache/commons/math4/analysis/differentiation/UnivariateDifferentiableFunction.html">
- UnivariateDifferentiableFunction</a> interface. Any differentiable function should implement this
- interface.
- </p>
- <p>
- The main idea behind the <a href="../apidocs/org/apache/commons/math4/analysis/differentiation/DerivativeStructure.html">
- DerivativeStructure</a> class is that it can be used almost as a number (i.e. it can be added,
- multiplied, its square root can be extracted or its cosine computed... However, in addition to
- computed the value itself when doing these computations, the partial derivatives are also computed
- alongside. This is an extension of what is sometimes called Rall's numbers. This extension is
- described in Dan Kalman's paper <a
- href="http://www1.american.edu/cas/mathstat/People/kalman/pdffiles/mmgautodiff.pdf">Doubly Recursive
- Multivariate Automatic Differentiation</a>, Mathematics Magazine, vol. 75, no. 3, June 2002.
- Rall's numbers only hold the first derivative with respect to one free parameter whereas Dan Kalman's
- derivative structures hold all partial derivatives up to any specified order, with respect to any
- number of free parameters. Rall's numbers therefore can be seen as derivative structures for order
- one derivative and one free parameter, and primitive real numbers can be seen as derivative structures
- with zero order derivative and no free parameters.
- </p>
- <p>
- The workflow of computation of a derivatives of an expression <code>y=f(x)</code> is the following
- one. First we configure an input parameter <code>x</code> of type <a
- href="../apidocs/org/apache/commons/math4/analysis/differentiation/DerivativeStructure.html">
- DerivativeStructure</a> so it will drive the function to compute all derivatives up to order 3 for
- example. Then we compute <code>y=f(x)</code> normally by passing this parameter to the f function.At
- the end, we extract from <code>y</code> the value and the derivatives we want. As we have specified
- 3<sup>rd</sup> order when we built <code>x</code>, we can retrieve the derivatives up to 3<sup>rd</sup>
- order from <code>y</code>. The following example shows that (the 0 parameter in the DerivativeStructure
- constructor will be explained in the next paragraph):
- </p>
- <source>int params = 1;
-int order = 3;
-double xRealValue = 2.5;
-DerivativeStructure x = new DerivativeStructure(params, order, 0, xRealValue);
-DerivativeStructure y = f(x);
-System.out.println("y = " + y.getValue();
-System.out.println("y' = " + y.getPartialDerivative(1);
-System.out.println("y'' = " + y.getPartialDerivative(2);
-System.out.println("y''' = " + y.getPartialDerivative(3);</source>
- <p>
- In fact, there are no notions of <em>variables</em> in the framework, so neither <code>x</code>
- nor <code>y</code> are considered to be variables per se. They are both considered to be
- <em>functions</em> and to depend on implicit free parameters which are represented only by
- indices in the framework. The <code>x</code> instance above is there considered by the framework
- to be a function of free parameter <code>p0</code> at index 0, and as <code>y</code> is
- computed from <code>x</code> it is the result of a functions composition and is therefore also
- a function of this <code>p0</code> free parameter. The <code>p0</code> is not represented by itself,
- it is simply defined implicitely by the 0 index above. This index is the third argument in the
- constructor of the <code>x</code> instance. What this constructor means is that we built
- <code>x</code> as a function that depends on one free parameter only (first constructor argument
- set to 1), that can be differentiated up to order 3 (second constructor argument set to 3), and
- which correspond to an identity function with respect to implicit free parameter number 0 (third
- constructor argument set to 0), with current value equal to 2.5 (fourth constructor argument set
- to 2.5). This specific constructor defines identity functions, and identity functions are the trick
- we use to represent variables (there are of course other constructors, for example to build constants
- or functions from all their derivatives if they are known beforehand). From the user point of view,
- the <code>x</code> instance can be seen as the <code>x</code> variable, but it is really the identity
- function applied to free parameter number 0. As the identity function, it has the same value as its
- parameter, its first derivative is 1.0 with respect to this free parameter, and all its higher order
- derivatives are 0.0. This can be checked by calling the getValue() or getPartialDerivative() methods
- on <code>x</code>.
- </p>
- <p>
- When we compute <code>y</code> from this setting, what we really do is chain <code>f</code> after the
- identity function, so the net result is that the derivatives are computed with respect to the indexed
- free parameters (i.e. only free parameter number 0 here since there is only one free parameter) of the
- identity function x. Going one step further, if we compute <code>z = g(y)</code>, we will also compute
- <code>z</code> as a function of the initial free parameter. The very important consequence is that
- if we call <code>z.getPartialDerivative(1)</code>, we will not get the first derivative of <code>g</code>
- with respect to <code>y</code>, but with respect to the free parameter <code>p0</code>: the derivatives
- of g and f <em>will</em> be chained together automatically, without user intervention.
- </p>
- <p>
- This design choice is a very classical one in many algorithmic differentiation frameworks, either
- based on operator overloading (like the one we implemented here) or based on code generation. It implies
- the user has to <em>bootstrap</em> the system by providing initial derivatives, and this is essentially
- done by setting up identity function, i.e. functions that represent the variables themselves and have
- only unit first derivative.
- </p>
- <p>
- This design also allow a very interesting feature which can be explained with the following example.
- Suppose we have a two arguments function <code>f</code> and a one argument function <code>g</code>. If
- we compute <code>g(f(x, y))</code> with <code>x</code> and <code>y</code> be two variables, we
- want to be able to compute the partial derivatives <code>dg/dx</code>, <code>dg/dy</code>,
- <code>d2g/dx2</code> <code>d2g/dxdy</code> <code>d2g/dy2</code>. This does make sense since we combined
- the two functions, and it does make sense despite g is a one argument function only. In order to do
- this, we simply set up <code>x</code> as an identity function of an implicit free parameter
- <code>p0</code> and <code>y</code> as an identity function of a different implicit free parameter
- <code>p1</code> and compute everything directly. In order to be able to combine everything, however,
- both <code>x</code> and <code>y</code> must be built with the appropriate dimensions, so they will both
- be declared to handle two free parameters, but <code>x</code> will depend only on parameter 0 while
- <code>y</code> will depend on parameter 1. Here is how we do this (note that
- <code>getPartialDerivative</code> is a variable arguments method which take as arguments the derivation
- order with respect to all free parameters, i.e. the first argument is derivation order with respect to
- free parameter 0 and the second argument is derivation order with respect to free parameter 1):
- </p>
- <source>int params = 2;
-int order = 2;
-double xRealValue = 2.5;
-double yRealValue = -1.3;
-DerivativeStructure x = new DerivativeStructure(params, order, 0, xRealValue);
-DerivativeStructure y = new DerivativeStructure(params, order, 1, yRealValue);
-DerivativeStructure f = DerivativeStructure.hypot(x, y);
-DerivativeStructure g = f.log();
-System.out.println("g = " + g.getValue();
-System.out.println("dg/dx = " + g.getPartialDerivative(1, 0);
-System.out.println("dg/dy = " + g.getPartialDerivative(0, 1);
-System.out.println("d2g/dx2 = " + g.getPartialDerivative(2, 0);
-System.out.println("d2g/dxdy = " + g.getPartialDerivative(1, 1);
-System.out.println("d2g/dy2 = " + g.getPartialDerivative(0, 2);</source>
- <p>
- There are several ways a user can create an implementation of the <a
- href="../apidocs/org/apache/commons/math4/analysis/differentiation/UnivariateDifferentiableFunction.html">
- UnivariateDifferentiableFunction</a> interface. The first method is to simply write it directly using
- the appropriate methods from <a href="../apidocs/org/apache/commons/math4/analysis/differentiation/DerivativeStructure.html">
- DerivativeStructure</a> to compute addition, subtraction, sine, cosine... This is often quite
- straigthforward and there is no need to remember the rules for differentiation: the user code only
- represent the function itself, the differentials will be computed automatically under the hood. The
- second method is to write a classical <a
- href="../apidocs/org/apache/commons/math4/analysis/UnivariateFunction.html">UnivariateFunction</a> and to
- pass it to an existing implementation of the <a
- href="../apidocs/org/apache/commons/math4/analysis/differentiation/UnivariateFunctionDifferentiator.html">
- UnivariateFunctionDifferentiator</a> interface to retrieve a differentiated version of the same function.
- The first method is more suited to small functions for which user already control all the underlying code.
- The second method is more suited to either large functions that would be cumbersome to write using the
- <a href="../apidocs/org/apache/commons/math4/analysis/differentiation/DerivativeStructure.html">
- DerivativeStructure</a> API, or functions for which user does not have control to the full underlying code
- (for example functions that call external libraries).
- </p>
- <p>
- Apache Commons Math provides one implementation of the <a
- href="../apidocs/org/apache/commons/math4/analysis/differentiation/UnivariateFunctionDifferentiator.html">
- UnivariateFunctionDifferentiator</a> interface: <a
- href="../apidocs/org/apache/commons/math4/analysis/differentiation/FiniteDifferencesDifferentiator.html">
- FiniteDifferencesDifferentiator</a>. This class creates a wrapper that will call the user-provided function
- on a grid sample and will use finite differences to compute the derivatives. It takes care of boundaries
- if the variable is not defined on the whole real line. It is possible to use more points than strictly
- required by the derivation order (for example one can specify an 8-points scheme to compute first
- derivative only). However, one must be aware that tuning the parameters for finite differences is
- highly problem-dependent. Choosing the wrong step size or the wrong number of sampling points can lead
- to huge errors. Finite differences are also not well suited to compute high order derivatives. Here is
- an example on how this implementation can be used:
- </p>
- <source>// function to be differentiated
-UnivariateFunction basicF = new UnivariateFunction() {
- public double value(double x) {
- return x * FastMath.sin(x);
- }
- });
-
-// create a differentiator using 5 points and 0.01 step
-FiniteDifferencesDifferentiator differentiator =
- new FiniteDifferencesDifferentiator(5, 0.01);
-
-// create a new function that computes both the value and the derivatives
-// using DerivativeStructure
-UnivariateDifferentiableFunction completeF = differentiator.differentiate(basicF);
-
-// now we can compute display the value and its derivatives
-// here we decided to display up to second order derivatives,
-// because we feed completeF with order 2 DerivativeStructure instances
-for (double x = -10; x < 10; x += 0.1) {
- DerivativeStructure xDS = new DerivativeStructure(1, 2, 0, x);
- DerivativeStructure yDS = f.value(xDS);
- System.out.format(Locale.US, "%7.3f %7.3f %7.3f%n",
- yDS.getValue(),
- yDS.getPartialDerivative(1),
- yDS.getPartialDerivative(2));
-}</source>
- <p>
- Note that using <a
- href="../apidocs/org/apache/commons/math4/analysis/differentiation/FiniteDifferencesDifferentiator.html">
- FiniteDifferencesDifferentiator</a>a> in order to have a <a
- href="../apidocs/org/apache/commons/math4/analysis/differentiation/UnivariateDifferentiableFunction.html">
- UnivariateDifferentiableFunction</a> that can be provided to a <a href="../apidocs/org/apache/commons/math4/analysis/solvers/NewtonRaphsonSolver.html">Newton-Raphson's</a>
- solver is a very bad idea. The reason is that finite differences are not really accurate and needs lots
- of additional calls to the basic underlying function. If user initially have only the basic function
- available and needs to find its roots, it is <em>much</em> more accurate and <em>much</em> more
- efficient to use a solver that only requires the function values and not the derivatives. A good choice is
- to use <a href="../apidocs/org/apache/commons/math4/analysis/solvers/BracketingNthOrderBrentSolver.html">bracketing
- n<sup>th</sup> order Brent</a> method, which in fact converges faster than <a
- href="../apidocs/org/apache/commons/math4/analysis/solvers/NewtonRaphsonSolver.html">Newton-Raphson's</a> and
- can be configured to a highere order (typically 5) than Newton-Raphson which is an order 2 method.
- </p>
- <p>
- Another implementation of the <a
- href="../apidocs/org/apache/commons/math4/analysis/differentiation/UnivariateFunctionDifferentiator.html">
- UnivariateFunctionDifferentiator</a> interface is under development in the related project
- <a href="http://commons.apache.org/sandbox/nabla/">Apache Commons Nabla</a>. This implementation uses
- automatic code analysis and generation at binary level. However, at time of writing
- (end 2012), this project is not yet suitable for production use.
- </p>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/complex.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/complex.xml b/src/site/xdoc/userguide/complex.xml
deleted file mode 100644
index f451ab1..0000000
--- a/src/site/xdoc/userguide/complex.xml
+++ /dev/null
@@ -1,145 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="stat.html">
- <properties>
- <title>The Commons Math User Guide - Complex Numbers</title>
- </properties>
- <body>
- <section name="7 Complex Numbers">
- <subsection name="7.1 Overview" href="overview">
- <p>
- The complex packages provides a complex number type as well as complex
- versions of common transcendental functions and complex number
- formatting.
- </p>
- </subsection>
- <subsection name="7.2 Complex Numbers" href="complex">
- <p>
- <a href="../apidocs/org/apache/commons/math4/complex/Complex.html">
- 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/math4/complex/Complex.html">
- Complex</a> and
- <a href="../apidocs/org/apache/commons/math4/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:
- <source>Complex c = new Complex(1.0, 3.0); // 1 + 3i</source>
- </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>:
- <source>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</source>
- </p>
- </subsection>
- <subsection name="7.3 Complex Transcendental Functions" href="function">
- <p>
- <a href="../apidocs/org/apache/commons/math4/complex/Complex.html">
- Complex</a> also provides implementations of serveral transcendental
- functions involving complex number arguments.
- These operations provide the means to compute the log, sine, tangent,
- and other complex values :
- <source>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</source>
- </p>
- </subsection>
- <subsection name="7.4 Complex Formatting and Parsing" href="formatting">
- <p>
- <code>Complex</code> instances can be converted to and from strings
- using the<a href="../apidocs/org/apache/commons/math4/complex/ComplexFormat.html">
- 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>):
- <source>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"</source>
- </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:
- <source>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"</source>
- </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:
- <source>ComplexFormat cf = new ComplexFormat();
-Complex c = cf.parse("1.110 + 2.222i");</source>
- </p>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/core.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/core.xml b/src/site/xdoc/userguide/core.xml
new file mode 100644
index 0000000..35a1356
--- /dev/null
+++ b/src/site/xdoc/userguide/core.xml
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+
+<!--
+ 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.
+ -->
+
+<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
+<document>
+ <properties>
+ <title>User Guide - Module "core"</title>
+ </properties>
+
+<body>
+
+<section name="Core">
+
+<subsection name="1.1 Section" href="section">
+ <p>
+ Contribution welcome...
+ </p>
+</subsection>
+
+</section>
+
+</body>
+</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/distribution.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/distribution.xml b/src/site/xdoc/userguide/distribution.xml
deleted file mode 100644
index 6fa61f8..0000000
--- a/src/site/xdoc/userguide/distribution.xml
+++ /dev/null
@@ -1,117 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="distribution.html">
- <properties>
- <title>The Commons Math User Guide - Distributions</title>
- </properties>
- <body>
- <section name="8 Probability Distributions">
- <subsection name="8.1 Overview" href="overview">
- <p>
- The distributions package provides a framework and implementations for some commonly used
- probability distributions. Continuous univariate distributions are represented by implementations of
- the <a href="../apidocs/org/apache/commons/math4/distribution/RealDistribution.html">RealDistribution</a>
- interface. Discrete distributions implement
- <a href="../apidocs/org/apache/commons/math4/distribution/IntegerDistribution.html">IntegerDistribution</a>
- (values must be mapped to integers) and there is an
- <a href="../apidocs/org/apache/commons/math4/distribution/EnumeratedDistribution.html">EnumeratedDistribution</a>
- class representing discrete distributions with a finite, enumerated set of values. Finally, multivariate
- real-valued distributions can be represented via the
- <a href="../apidocs/org/apache/commons/math4/distribution/MultiVariateRealDistribution.html">MultivariateRealDistribution</a>
- interface.
- </p>
- <p>
- An overview of available continuous distributions:<br/>
- <img src="../images/userguide/real_distribution_examples.png" alt="Overview of continuous distributions"/>
- </p>
- </subsection>
- <subsection name="8.2 Distribution Framework" href="distributions">
- <p>
- The distribution framework provides the means to compute probability density
- functions (<code>density(·)</code>), probability mass functions
- (<code>probability(·)</code>) and distribution functions
- (<code>cumulativeProbability(·)</code>) for both
- discrete (integer-valued) and continuous probability distributions.
- The framework also allows for the computation of inverse cumulative probabilities
- and sampling from distributions.
- </p>
- <p>
- For an instance <code>f</code> of a distribution <code>F</code>,
- and a domain value, <code>x</code>, <code>f.cumulativeProbability(x)</code>
- computes <code>P(X <= x)</code> where <code>X</code> is a random variable distributed
- as <code>f</code>, i.e., <code>f.cumulativeProbability(·)</code> represents
- the distribution function of <code>f</code>. If <code>f</code> is continuous,
- (implementing the <code>RealDistribution</code> interface) the probability density
- function of <code>f</code> is represented by <code>f.density(·)</code>.
- For discrete <code>f</code> (implementing <code>IntegerDistribution</code>), the probability
- mass function is represented by <code>f.probability(·)</code>. Continuous
- distributions also implement <code>probability(·)</code> with the same
- definition (<code>f.probability(x)</code> represents <code>P(X = x)</code>
- where <code>X</code> is distributed as <code>f</code>), though in the continuous
- case, this will usually be identically 0.
- </p>
-<source>TDistribution t = new TDistribution(29);
-double lowerTail = t.cumulativeProbability(-2.656); // P(T(29) <= -2.656)
-double upperTail = 1.0 - t.cumulativeProbability(2.75); // P(T(29) >= 2.75)</source>
- <p>
- All distributions implement a <code>sample()</code> method to support random sampling from the
- distribution. Implementation classes expose constructors allowing the default
- <a href="../apidocs/org/apache/commons/math4/random/RandomGenerator.html">RandomGenerator</a>
- used by the sampling algorithm to be overridden. If sampling is not going to be used, providing
- a null <code>RandomGenerator</code> constructor argument will avoid the overhead of initializing
- the default generator.
- </p>
- <p>
- Inverse distribution functions can be computed using the
- <code>inverseCumulativeProbability</code> methods. For continuous <code>f</code>
- and <code>p</code> a probability, <code>f.inverseCumulativeProbability(p)</code> returns
- <code><ul>
- <li>inf{x in R | P(X≤x) ≥ p} for 0 < p < 1},</li>
- <li>inf{x in R | P(X≤x) > 0} for p = 0}.</li>
- </ul></code> where <code>X</code> is distributed as <code>f</code>.<br/>
- For discrete <code>f</code>, the definition is the same, with <code>Z</code> (the integers)
- in place of <code>R</code>. Note that in the discrete case, the ≥ in the definition
- can make a difference when <code>p</code> is an attained value of the distribution.
- </p>
- </subsection>
- <!--
- TODO: add section on multivariate distributions
- -->
- <subsection name="8.3 User Defined Distributions" href="userdefined">
- <p>
- User-defined distributions can be implemented using
- <a href="../apidocs/org/apache/commons/math4/distribution/RealDistribution.html">RealDistribution</a>,
- <a href="../apidocs/org/apache/commons/math4/distribution/IntegerDistribution.html">IntegerDistribution</a> and
- <a href="../apidocs/org/apache/commons/math4/distribution/MultivariateRealDistribution.html">MultivariateRealDistribution</a>
- interfaces serve as base types. These serve as the basis for all the distributions directly supported by
- Apache Commons Math. To aid in implementing distributions,
- the <a href="../apidocs/org/apache/commons/math4/distribution/AbstractRealDistribution.html">AbstractRealDistribution</a>,
- <a href="../apidocs/org/apache/commons/math4/distribution/AbstractIntegerDistribution.html">AbstractIntegerDistribution</a> and
- <a href="../apidocs/org/apache/commons/math4/distribution/AbstractMultivariateRealDistribution.html">AbstractMultivariateRealDistribution</a>
- provide implementation building blocks and offer basic distribution functionality.
- By extending these abstract classes directly, much of the repetitive distribution
- implementation is already developed and should save time and effort in developing
- user-defined distributions.
- </p>
- </subsection>
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/exceptions.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/exceptions.xml b/src/site/xdoc/userguide/exceptions.xml
deleted file mode 100644
index 4376116..0000000
--- a/src/site/xdoc/userguide/exceptions.xml
+++ /dev/null
@@ -1,119 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="exceptions.html">
- <properties>
- <title>The Commons Math User Guide - Exceptions</title>
- </properties>
- <body>
- <section name="19 Exceptions">
-
- <subsection name="19.1 Overview" href="overview">
- Commons Math defines a set of exceptions in order to convey the
- precise low-level cause of failure.
- </subsection>
-
- <subsection name="19.2 Unchecked Exceptions" href="unchecked">
- <p>
- Starting from version 3.0, all exceptions generated by the
- Commons Math code are <em>unchecked</em> (i.e. they inherit from
- the standard <code>RuntimeException</code> class).
- The main rationale supporting this design decision is that the
- exceptions generated in the library are not recoverable: They most
- of the time result from bad input parameters or some failure due to
- numerical problems.
- A thorough discussion of the pros and cons of checked and unchecked
- exceptions can be read in
- <a href="http://www.mindview.net/Etc/Discussions/CheckedExceptions">
- this post</a> by Bruce Eckel.
- </p>
- </subsection>
-
- <subsection name="19.3 Hierarchies" href="hierarchies">
- <p>
- The exceptions defined by Commons Math follow the Java standard
- hierarchies:
- <ul>
- <li>
- <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/IllegalArgumentException.html">
- <code>IllegalArgumentException</code></a>:
- A <a href="../apidocs/org/apache/commons/math4/exception/MathIllegalArgumentException.html">
- <code>MathIllegalArgumentException</code></a> is thrown when some input
- parameter fails a precondition check.
- </li>
- <li>
- <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/IllegalStateException.html">
- <code>IllegalStateException</code></a>:
- A <a href="../apidocs/org/apache/commons/math4/exception/MathIllegalStateException.html">
- <code>MathIllegalStateException</code></a> is thrown when some inconsistency
- has been detected.
- </li>
- <li>
- <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/MathArithmeticException.html">
- <code>ArithmeticException</code></a>:
- A <a href="../apidocs/org/apache/commons/math4/exception/MathArithmeticException.html">
- <code>MathArithmeticException</code></a> is thrown when conditions such as
- "division by zero" or "overflow" are encountered.
- </li>
- <li>
- <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/MathUnsupportedOperationException.html">
- <code>UnsupportedOperationException</code></a>:
- A <a href="../apidocs/org/apache/commons/math4/exception/MathUnsupportedOperationException.html">
- <code>MathUnsupportedOperationException</code></a> indicates that a feature
- is missing or does not make sense in the given context.
- </li>
- </ul>
- </p>
-
- <p>
- In all of the above exception hierarchies, several subclasses can
- exist, each conveying a specific underlying cause of the problem.
- </p>
- </subsection>
-
- <subsection name="19.4 Features" href="features">
- <ul>
- <li>Localization
- <p>
- The detailed error messages (i.e. the string returned by the
- <a href="http://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html#getLocalizedMessage()">
- getLocalizedMessage</a> method) can be localized.
- However, besides the American/English default, French is the only language
- for which a translation resource is available.
- </p>
- </li>
- <li>Exception "context"
- <p>
- Every exception generated by Commons Math implements the
- <a href="../apidocs/org/apache/commons/math4/exception/util/ExceptionContextProvider.html">
- ExceptionContextProvider</a> interface. A call to the
- <a href="../apidocs/org/apache/commons/math4/exception/util/ExceptionContextProvider.html#getContext()">
- getContext</a> method will return the
- <a href="../apidocs/org/apache/commons/math4/exception/util/ExceptionContext.html">
- ExceptionContext</a> instance stored in the exception, which the
- user can further customize by adding messages and/or any object.
- </p>
- </li>
- </ul>
- </subsection>
-
- </section>
- </body>
-</document>
http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/b36e21d9/src/site/xdoc/userguide/filter.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/filter.xml b/src/site/xdoc/userguide/filter.xml
deleted file mode 100644
index b298953..0000000
--- a/src/site/xdoc/userguide/filter.xml
+++ /dev/null
@@ -1,226 +0,0 @@
-<?xml version="1.0"?>
-
-<!--
- 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.
- -->
-
-<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<document url="filter.html">
- <properties>
- <title>The Commons Math User Guide - Filters</title>
- </properties>
- <body>
- <section name="17 Filters">
- <subsection name="17.1 Overview" href="overview">
- <p>
- The filter package currently provides only an implementation of a Kalman filter.
- </p>
- </subsection>
- <subsection name="17.2 Kalman Filter" href="kalman">
- <p>
- <a href="../apidocs/org/apache/commons/math4/filter/KalmanFilter.html">
- KalmanFilter</a> provides a discrete-time filter to estimate
- a stochastic linear process.</p>
-
- <p>A Kalman filter is initialized with a <a href="../apidocs/org/apache/commons/math4/filter/ProcessModel.html">
- ProcessModel</a> and a <a href="../apidocs/org/apache/commons/math4/filter/MeasurementModel.html">
- MeasurementModel</a>, which contain the corresponding transformation and noise covariance matrices.
- The parameter names used in the respective models correspond to the following names commonly used
- in the mathematical literature:
- <ul>
- <li>A - state transition matrix</li>
- <li>B - control input matrix</li>
- <li>H - measurement matrix</li>
- <li>Q - process noise covariance matrix</li>
- <li>R - measurement noise covariance matrix</li>
- <li>P - error covariance matrix</li>
- </ul>
- </p>
- <p>
- <dl>
- <dt>Initialization</dt>
- <dd> The following code will create a Kalman filter using the provided
- DefaultMeasurementModel and DefaultProcessModel classes. To support dynamically changing
- process and measurement noises, simply implement your own models.
- <source>
-// A = [ 1 ]
-RealMatrix A = new Array2DRowRealMatrix(new double[] { 1d });
-// no control input
-RealMatrix B = null;
-// H = [ 1 ]
-RealMatrix H = new Array2DRowRealMatrix(new double[] { 1d });
-// Q = [ 0 ]
-RealMatrix Q = new Array2DRowRealMatrix(new double[] { 0 });
-// R = [ 0 ]
-RealMatrix R = new Array2DRowRealMatrix(new double[] { 0 });
-
-ProcessModel pm
- = new DefaultProcessModel(A, B, Q, new ArrayRealVector(new double[] { 0 }), null);
-MeasurementModel mm = new DefaultMeasurementModel(H, R);
-KalmanFilter filter = new KalmanFilter(pm, mm);
- </source>
- </dd>
- <dt>Iteration</dt>
- <dd>The following code illustrates how to perform the predict/correct cycle:
- <source>
-for (;;) {
- // predict the state estimate one time-step ahead
- // optionally provide some control input
- filter.predict();
-
- // obtain measurement vector z
- RealVector z = getMeasurement();
-
- // correct the state estimate with the latest measurement
- filter.correct(z);
-
- double[] stateEstimate = filter.getStateEstimation();
- // do something with it
-}
- </source>
- </dd>
- <dt>Constant Voltage Example</dt>
- <dd>The following example creates a Kalman filter for a static process: a system with a
- constant voltage as internal state. We observe this process with an artificially
- imposed measurement noise of 0.1V and assume an internal process noise of 1e-5V.
- <source>
-double constantVoltage = 10d;
-double measurementNoise = 0.1d;
-double processNoise = 1e-5d;
-
-// A = [ 1 ]
-RealMatrix A = new Array2DRowRealMatrix(new double[] { 1d });
-// B = null
-RealMatrix B = null;
-// H = [ 1 ]
-RealMatrix H = new Array2DRowRealMatrix(new double[] { 1d });
-// x = [ 10 ]
-RealVector x = new ArrayRealVector(new double[] { constantVoltage });
-// Q = [ 1e-5 ]
-RealMatrix Q = new Array2DRowRealMatrix(new double[] { processNoise });
-// P = [ 1 ]
-RealMatrix P0 = new Array2DRowRealMatrix(new double[] { 1d });
-// R = [ 0.1 ]
-RealMatrix R = new Array2DRowRealMatrix(new double[] { measurementNoise });
-
-ProcessModel pm = new DefaultProcessModel(A, B, Q, x, P0);
-MeasurementModel mm = new DefaultMeasurementModel(H, R);
-KalmanFilter filter = new KalmanFilter(pm, mm);
-
-// process and measurement noise vectors
-RealVector pNoise = new ArrayRealVector(1);
-RealVector mNoise = new ArrayRealVector(1);
-
-RandomGenerator rand = new JDKRandomGenerator();
-// iterate 60 steps
-for (int i = 0; i < 60; i++) {
- filter.predict();
-
- // simulate the process
- pNoise.setEntry(0, processNoise * rand.nextGaussian());
-
- // x = A * x + p_noise
- x = A.operate(x).add(pNoise);
-
- // simulate the measurement
- mNoise.setEntry(0, measurementNoise * rand.nextGaussian());
-
- // z = H * x + m_noise
- RealVector z = H.operate(x).add(mNoise);
-
- filter.correct(z);
-
- double voltage = filter.getStateEstimation()[0];
-}
- </source>
- </dd>
- <dt>Increasing Speed Vehicle Example</dt>
- <dd>The following example creates a Kalman filter for a simple linear process: a
- vehicle driving along a street with a velocity increasing at a constant rate. The process
- state is modeled as (position, velocity) and we only observe the position. A measurement
- noise of 10m is imposed on the simulated measurement.
- <source>
-// discrete time interval
-double dt = 0.1d;
-// position measurement noise (meter)
-double measurementNoise = 10d;
-// acceleration noise (meter/sec^2)
-double accelNoise = 0.2d;
-
-// A = [ 1 dt ]
-// [ 0 1 ]
-RealMatrix A = new Array2DRowRealMatrix(new double[][] { { 1, dt }, { 0, 1 } });
-// B = [ dt^2/2 ]
-// [ dt ]
-RealMatrix B = new Array2DRowRealMatrix(new double[][] { { Math.pow(dt, 2d) / 2d }, { dt } });
-// H = [ 1 0 ]
-RealMatrix H = new Array2DRowRealMatrix(new double[][] { { 1d, 0d } });
-// x = [ 0 0 ]
-RealVector x = new ArrayRealVector(new double[] { 0, 0 });
-
-RealMatrix tmp = new Array2DRowRealMatrix(new double[][] {
- { Math.pow(dt, 4d) / 4d, Math.pow(dt, 3d) / 2d },
- { Math.pow(dt, 3d) / 2d, Math.pow(dt, 2d) } });
-// Q = [ dt^4/4 dt^3/2 ]
-// [ dt^3/2 dt^2 ]
-RealMatrix Q = tmp.scalarMultiply(Math.pow(accelNoise, 2));
-// P0 = [ 1 1 ]
-// [ 1 1 ]
-RealMatrix P0 = new Array2DRowRealMatrix(new double[][] { { 1, 1 }, { 1, 1 } });
-// R = [ measurementNoise^2 ]
-RealMatrix R = new Array2DRowRealMatrix(new double[] { Math.pow(measurementNoise, 2) });
-
-// constant control input, increase velocity by 0.1 m/s per cycle
-RealVector u = new ArrayRealVector(new double[] { 0.1d });
-
-ProcessModel pm = new DefaultProcessModel(A, B, Q, x, P0);
-MeasurementModel mm = new DefaultMeasurementModel(H, R);
-KalmanFilter filter = new KalmanFilter(pm, mm);
-
-RandomGenerator rand = new JDKRandomGenerator();
-
-RealVector tmpPNoise = new ArrayRealVector(new double[] { Math.pow(dt, 2d) / 2d, dt });
-RealVector mNoise = new ArrayRealVector(1);
-
-// iterate 60 steps
-for (int i = 0; i < 60; i++) {
- filter.predict(u);
-
- // simulate the process
- RealVector pNoise = tmpPNoise.mapMultiply(accelNoise * rand.nextGaussian());
-
- // x = A * x + B * u + pNoise
- x = A.operate(x).add(B.operate(u)).add(pNoise);
-
- // simulate the measurement
- mNoise.setEntry(0, measurementNoise * rand.nextGaussian());
-
- // z = H * x + m_noise
- RealVector z = H.operate(x).add(mNoise);
-
- filter.correct(z);
-
- double position = filter.getStateEstimation()[0];
- double velocity = filter.getStateEstimation()[1];
-}
- </source>
- </dd>
- </dl>
- </p>
- </subsection>
- </section>
- </body>
-</document>