<?xml version="1.0"?>

<!--
   Copyright 2003-2004 The Apache Software Foundation

   Licensed 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"?>
<!-- $Revision$ $Date$ -->
<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>
           Currently, numerical linear algebra support in commons-math is 
           limited to basic operations on real matrices and solving linear systems.
        </p>
      </subsection>
      <subsection name="3.2 Real matrices" href="real_matrices">
        <p>
          The <a href="../apidocs/org/apache/commons/math/linear/RealMatrix.html">
          RealMatrix</a> interface represents a matrix with real numbers as 
          entries.  The following basic matrix operations are supported:
          <ul>
          <li>Matrix addition, subtraction, mutiplication</li>
          <li>Scalar addition and multiplication</li>
          <li>Inverse and transpose</li>
          <li>Determinants and singularity testing</li>
          <li>LU decomposition</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
double[][] matrixData = { {1d,2d,3d}, {2d,5d,3d}};
RealMatrix m = new RealMatrixImpl(matrixData);

// One more with three rows, two columns
double[][] matrixData2 = { {1d,2d}, {2d,5d}, {1d, 7d}};
RealMatrix n = new RealMatixImpl(matrixData2);

// Note: constructor makes a
// Fresh copy of the input double[][] array

// Now multiply m by n
RealMatrix p = m.multiply(n);
System.out.println(p.getRowDimension()); // 2
System.out.println(p.getRowDimension()); // 2

// Invert p
RealMatrix pInverse = p.inverse();
         </source>
        </p>         
      </subsection>
      <subsection name="3.3 Solving linear systems" href="solve">
        <p>
          The <code>solve()</code> methods of the <code>RealMatrix</code> interface
          support solving linear systems of equations.  In each case, the 
          <code>RealMatrix</code> represents the coefficient matrix of the system.
          For example, to solve the linear system
          <pre>
           2x + 3y - 2z = 1
           -x + 7y + 6x = -2
           4x - 3y - 5z = 1
          </pre>
          Start by creating a RealMatrix to store the coefficients
          <source>
double[][] coefficientsData = {{2, 3, -2}, {-1, 7, 6}, {4, -3, -5}};
RealMatrix coefficients = new RealMatrixImpl(coefficientsData);
          </source>
          Next create a <code>double[]</code> array to represent the constant
          vector and use <code>solve(double[])</code> to solve the system
          <source>
double[] constants = {1, -2, 1};
double[] solution = coefficients.solve(constants);
          </source>
          The <code>solution</code> array will contain values for x 
          (<code>solution[0]</code>), y (<code>solution[1]</code>), 
          and z (<code>solution[2]</code>) that solve the system.
        </p>
        <p>
          If the coefficient matrix is not square or singular, an 
          <a href="../apidocs/org/apache/commons/math/linear/InvalidMatrixException.html">
          InvalidMatrixException</a> is thrown.
        </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>
    </section>
  </body>
</document>