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:17 UTC
[4/5] commons-numbers git commit: NUMBERS-70: Delete files describing
"Commons Math" (userguide).
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>