This is NumericalLinearAlgebra.info, produced by Macaulay2, version 1.20

NumericalLinearAlgebra -- numerical linear algebra
**************************************************

Description
===========

This package collects implementations of numerical linear algebra algorithms.

  * numericalRank
  * numericalKernel
  * numericalImage
  * colReduce

Authors
=======

  * Robert Krone <krone@math.gatech.edu>
  * Marc Harkonen <harkonen@gatech.edu>
  * Anton Leykin <anton.leykin@gmail.com>

Version
=======

This documentation describes version 1.16 of NumericalLinearAlgebra.

Source code
===========

The source code from which this documentation is derived is in the file
NumericalLinearAlgebra.m2 (see common/share/Macaulay2/NumericalLinearAlgebra.m2
).

Exports
=======

  * Functions and commands
      * colReduce -- column reduce a matrix
      * numericalImage -- Image of a matrix
      * numericalKernel -- approximate kernel of a
        matrix
      * "isFullNumericalRank" -- see numericalRank, --
        numerical rank of a matrix
      * numericalRank -- numerical rank of a matrix
  * Methods
      * "colReduce(Matrix)" -- see colReduce, -- column reduce
        a matrix
      * "numericalImage(Matrix)" -- see numericalImage,
        -- Image of a matrix
      * "numericalImage(Matrix,Number)" -- see numericalImage,
        -- Image of a matrix
      * "numericalKernel(Matrix)" -- see numericalKernel,
        -- approximate kernel of a matrix
      * "isFullNumericalRank(Matrix)" -- see numericalRank,
        -- numerical rank of a matrix
      * "numericalRank(Matrix)" -- see numericalRank, --
        numerical rank of a matrix
  * Symbols
      * "Normalize" -- see colReduce, -- column reduce a
        matrix
      * Tolerance -- the tolerance of a numerical computation

For the programmer
==================

The object NumericalLinearAlgebra, is a package (Macaulay2Doc).

colReduce -- column reduce a matrix
***********************************

Synopsis
========

  * Usage:
        N = colReduce M
  * Inputs:
      * M, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Normalize => ..., default value true
      * Reverse => ..., default value false
      * Tolerance, => ..., default
        value null, the tolerance of a numerical computation
  * Outputs:
      * N, a matrix (Macaulay2Doc), in reduced column echelon
        form

Description
===========

Performs Gaussian column reduction on a matrix M, retaining only the linearly
independent columns.

+----------------------------------------------------+
|i1 : M = matrix {{1., 2, 3}, {2, 4, 0}, {-1, -2, 3}}|
|                                                    |
|o1 = | 1  2  3 |                                    |
|     | 2  4  0 |                                    |
|     | -1 -2 3 |                                    |
|                                                    |
|                3          3                        |
|o1 : Matrix RR    <--- RR                           |
|              53         53                         |
+----------------------------------------------------+
|i2 : colReduce(M, Tolerance=>0.01)                  |
|                                                    |
|o2 = | 1 1 |                                        |
|     | 0 1 |                                        |
|     | 1 0 |                                        |
|                                                    |
|                3          2                        |
|o2 : Matrix RR    <--- RR                           |
|              53         53                         |
+----------------------------------------------------+

Entries with absolute value below the tolerance are treated as zero and not
used as pivots.

+---------------------------------------------------------+
|i3 : N = matrix {{0.001, 0, 0}, {1, 1, 3}, {2, 2, 5.999}}|
|                                                         |
|o3 = | .001 0 0     |                                    |
|     | 1    1 3     |                                    |
|     | 2    2 5.999 |                                    |
|                                                         |
|                3          3                             |
|o3 : Matrix RR    <--- RR                                |
|              53         53                              |
+---------------------------------------------------------+
|i4 : colReduce(N, Tolerance=>0.01)                       |
|                                                         |
|o4 = | 0       |                                         |
|     | .500083 |                                         |
|     | 1       |                                         |
|                                                         |
|                3          1                             |
|o4 : Matrix RR    <--- RR                                |
|              53         53                              |
+---------------------------------------------------------+

The lower rows are treated as the lead terms unless the optional argument
Reverse is set to true.

+--------------------------------+
|i5 : colReduce(M, Reverse=>true)|
|                                |
|o5 = | 1 0  |                   |
|     | 0 1  |                   |
|     | 1 -1 |                   |
|                                |
|                3          2    |
|o5 : Matrix RR    <--- RR       |
|              53         53     |
+--------------------------------+

If the optional argument Normalize is set to true (default) each vector is
normalized so that the lead entry is 1.  Otherwise this step is skipped.

+-----------------------------------+
|i6 : colReduce(M, Normalize=>false)|
|                                   |
|o6 = | 3 4 |                       |
|     | 0 4 |                       |
|     | 3 0 |                       |
|                                   |
|                3          2       |
|o6 : Matrix RR    <--- RR          |
|              53         53        |
+-----------------------------------+

Ways to use colReduce :
=======================

  * "colReduce(Matrix)"

For the programmer
==================

The object colReduce, is a method function with options (Macaulay2Doc).

numericalImage -- Image of a matrix
***********************************

Synopsis
========

  * Usage:
        V = numericalImage(M, tol)
  * Inputs:
      * M, a matrix (Macaulay2Doc),
      * tol, a number (Macaulay2Doc), a positive number, the
        numerical tolerance
  * Optional inputs (Macaulay2Doc),:
      * Tolerance, => ..., default
        value null, the tolerance of a numerical computation
  * Outputs:
      * V, a matrix (Macaulay2Doc),

Description
===========

Computes the image of a matrix M numerically using singular value
decomposition.

+--------------------------------------------------+
|i1 : M = matrix {{1., 0, 1}, {0, 1, 1}, {1, 0, 1}}|
|                                                  |
|o1 = | 1 0 1 |                                    |
|     | 0 1 1 |                                    |
|     | 1 0 1 |                                    |
|                                                  |
|                3          3                      |
|o1 : Matrix RR    <--- RR                         |
|              53         53                       |
+--------------------------------------------------+
|i2 : numericalImage(M, 0.01)                      |
|                                                  |
|o2 = | -.627963 -.325058 |                        |
|     | -.459701 .888074  |                        |
|     | -.627963 -.325058 |                        |
|                                                  |
|                3          2                      |
|o2 : Matrix RR    <--- RR                         |
|              53         53                       |
+--------------------------------------------------+

Singular values less than the tolerance are treated as zero.

+------------------------------------+
|i3 : M = matrix {{0.999, 2}, {1, 2}}|
|                                    |
|o3 = | .999 2 |                     |
|     | 1    2 |                     |
|                                    |
|                2          2        |
|o3 : Matrix RR    <--- RR           |
|              53         53         |
+------------------------------------+
|i4 : numericalImage(M, 0.01)        |
|                                    |
|o4 = | -.707036 |                   |
|     | -.707177 |                   |
|                                    |
|                2          1        |
|o4 : Matrix RR    <--- RR           |
|              53         53         |
+------------------------------------+

Ways to use numericalImage :
============================

  * "numericalImage(Matrix)"
  * "numericalImage(Matrix,Number)"

For the programmer
==================

The object numericalImage, is a method function with options (Macaulay2Doc).

numericalKernel -- approximate kernel of a matrix
*************************************************

Synopsis
========

  * Usage:
        V = numericalKernel(M)
  * Inputs:
      * M, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Tolerance, => ..., default
        value null, the tolerance of a numerical computation
  * Outputs:
      * V, a matrix (Macaulay2Doc),

Description
===========

Computes the kernel of a matrix M numerically using singular value
decomposition.

+----------------------------------------+
|i1 : M = matrix {{1., 1, 1}}            |
|                                        |
|o1 = | 1 1 1 |                          |
|                                        |
|                1          3            |
|o1 : Matrix RR    <--- RR               |
|              53         53             |
+----------------------------------------+
|i2 : numericalKernel(M, Tolerance=>0.01)|
|                                        |
|o2 = | -.57735  -.57735  |              |
|     | .788675  -.211325 |              |
|     | -.211325 .788675  |              |
|                                        |
|                3          2            |
|o2 : Matrix RR    <--- RR               |
|              53         53             |
+----------------------------------------+

Singular values less than the tolerance are treated as zero.

+----------------------------------------+
|i3 : M = matrix {{1., 1}, {1.001, 1}}   |
|                                        |
|o3 = | 1     1 |                        |
|     | 1.001 1 |                        |
|                                        |
|                2          2            |
|o3 : Matrix RR    <--- RR               |
|              53         53             |
+----------------------------------------+
|i4 : numericalKernel(M, Tolerance=>0.01)|
|                                        |
|o4 = | .70693   |                       |
|     | -.707284 |                       |
|                                        |
|                2          1            |
|o4 : Matrix RR    <--- RR               |
|              53         53             |
+----------------------------------------+

Ways to use numericalKernel :
=============================

  * "numericalKernel(Matrix)"

For the programmer
==================

The object numericalKernel, is a method function with options (Macaulay2Doc).

numericalRank -- numerical rank of a matrix
*******************************************

Synopsis
========

  * Usage:
        r = numericalRank M
        B = isFullNumericalRank M
  * Inputs:
      * M, a matrix (Macaulay2Doc), a matrix with real or complex
        entries
  * Optional inputs (Macaulay2Doc),:
      * Threshold => ..., default value .0001
  * Outputs:
      * r, an integer (Macaulay2Doc),
      * B, a Boolean value (Macaulay2Doc),

Description
===========

See numericalRank, finds an approximate rank of the matrix M.

See isFullNumericalRank, = M is _not_ rank-deficient.

Let \sigma_1,...,\sigma_n be the singular values of M.

If Threshold (LLLBases), is >1, then to establish numerical
rank we look for the first large gap between two consecutive singular values.
The gap between \sigma_i and \sigma_{i+1} is large if \sigma_i/\sigma_{i+1} >
See Threshold (LLLBases).

If Threshold (LLLBases), is <=1, then the rank equals the
number of singular values larger then Threshold (LLLBases).

+--------------------------------------------+
|i1 : options numericalRank                  |
|                                            |
|o1 = OptionTable{Threshold => .0001}        |
|                                            |
|o1 : OptionTable                            |
+--------------------------------------------+
|i2 : numericalRank matrix {{2,1},{0,0.001}} |
|                                            |
|o2 = 2                                      |
+--------------------------------------------+
|i3 : numericalRank matrix {{2,1},{0,0.0001}}|
|                                            |
|o3 = 1                                      |
+--------------------------------------------+

Caveat
======

We assume \sigma_0=1 above.

See also
========

  * SVD (Macaulay2Doc) -- singular value decomposition of a matrix

Ways to use numericalRank :
===========================

  * "numericalRank(Matrix)"

For the programmer
==================

The object numericalRank, is a method function with options (Macaulay2Doc).

Tolerance -- the tolerance of a numerical computation
*****************************************************

Functions with optional argument named Tolerance :
==================================================

  * "colReduce(...,Tolerance=>...)" -- see
    Tolerance(NumericalLinearAlgebra),
    -- the tolerance of a numerical computation
  * "numericalImage(...,Tolerance=>...)" -- see
    Tolerance(NumericalLinearAlgebra),
    -- the tolerance of a numerical computation
  * "numericalKernel(...,Tolerance=>...)" -- see
    Tolerance(NumericalLinearAlgebra),
    -- the tolerance of a numerical computation

For the programmer
==================

The object Tolerance, is a symbol (Macaulay2Doc).

Tolerance(NumericalLinearAlgebra) -- the tolerance of a numerical computation
*****************************************************************************

The default value null sets tolerance to 1e-6.