src/site/xdoc/userguide/linear.xml - commons-math - Git at Google

 <?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 + 6z = -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>
	<?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 + 6z = -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>