Skip to content

Commit fea597c

Browse files
ViralBShahViralBShah
committed
Merge pull request #2807 from jiahao/doc-special-matrices
RFC: Expands array doc
2 parents a7b6dbd + 29e9510 commit fea597c

File tree

3 files changed

+182
-7
lines changed

3 files changed

+182
-7
lines changed

‎doc/manual/arrays.rst

+179-7
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ that the result is of type ``Float64`` by writing::
143143

144144
Float64[ 0.25*x[i-1] + 0.5*x[i] + 0.25*x[i+1] for i=2:length(x)-1 ]
145145

146-
Using curly brackets instead of square brackets is a shortand notation for an
146+
Using curly brackets instead of square brackets is a shorthand notation for an
147147
array of type ``Any``::
148148

149149
julia> { i/2 for i = 1:3 }
@@ -385,6 +385,128 @@ stride parameters.
385385
-1.175 -0.786311
386386
0.0 -0.414549
387387
388+
***********************
389+
Matrix factorizations
390+
***********************
391+
392+
`Matrix factorizations (a.k.a. matrix decompositions) <http://en.wikipedia.org/wiki/Matrix_decomposition>`_
393+
compute the factorization of a matrix into a product of matrices, and
394+
are one of the central concepts in linear algebra.
395+
396+
The following table summarizes the types of matrix factorizations that have been
397+
implemented in Julia. Details of their associated methods can be found
398+
in the :ref:`stdlib-linalg` section of the standard library documentation.
399+
400+
=================== ===========
401+
``Cholesky`` `Cholesky factorization <http://en.wikipedia.org/wiki/Cholesky_decomposition>`_
402+
``CholeskyPivoted`` `Pivoted <http://en.wikipedia.org/wiki/Pivot_element>`_ Cholesky factorization
403+
``LU`` `LU factorization <http://en.wikipedia.org/wiki/LU_decomposition>`_
404+
``QRPivoted`` Pivoted `QR factorization <http://en.wikipedia.org/wiki/QR_decomposition>`_
405+
``Hessenberg`` `Hessenberg decomposition <http://mathworld.wolfram.com/HessenbergDecomposition.html>`_
406+
``Eigen`` `Spectral decomposition <http://en.wikipedia.org/wiki/Eigendecomposition_(matrix)>`_
407+
``SVD`` `Singular value decomposition <http://en.wikipedia.org/wiki/Singular_value_decomposition>`_
408+
``GeneralizedSVD`` `Generalized SVD <http://en.wikipedia.org/wiki/Generalized_singular_value_decomposition#Higher_order_version>`_
409+
=================== ===========
410+
411+
******************
412+
Special matrices
413+
******************
414+
415+
`Matrices with special symmetries and structures <http://www2.imm.dtu.dk/pubdb/views/publication_details.php?id=3274>`_
416+
arise often in linear algebra and are frequently associated with
417+
various matrix factorizations.
418+
Julia features a rich collection of special matrix types, which allow for fast
419+
computation with specialized routines that are specially developed for
420+
particular matrix types.
421+
422+
The following tables summarize the types of special matrices that have been
423+
implemented in Julia, as well as whether hooks to various optimized methods
424+
for them in LAPACK are available.
425+
426+
+--------------------+-----------------------------------------------------------------------------------+
427+
| ``Hermitian`` | `Hermitian matrix <http://en.wikipedia.org/wiki/Hermitian_matrix>`_ |
428+
+--------------------+-----------------------------------------------------------------------------------+
429+
| ``Triangular`` | Upper/lower `triangular matrix <http://en.wikipedia.org/wiki/Triangular_matrix>`_ |
430+
+--------------------+-----------------------------------------------------------------------------------+
431+
| ``Tridiagonal`` | `Tridiagonal matrix <http://en.wikipedia.org/wiki/Tridiagonal_matrix>`_ |
432+
+--------------------+-----------------------------------------------------------------------------------+
433+
| ``SymTridiagonal`` | Symmetric tridiagonal matrix |
434+
+--------------------+-----------------------------------------------------------------------------------+
435+
| ``Bidiagonal`` | Upper/lower `bidiagonal matrix <http://en.wikipedia.org/wiki/Bidiagonal_matrix>`_ |
436+
+--------------------+-----------------------------------------------------------------------------------+
437+
| ``Diagonal`` | `Diagonal matrix <http://en.wikipedia.org/wiki/Diagonal_matrix>`_ |
438+
+--------------------+-----------------------------------------------------------------------------------+
439+
440+
441+
Elementary operations
442+
---------------------
443+
444+
+--------------------+-------+-------+-------+-------+---------------------+
445+
| Matrix type | ``+`` | ``-`` | ``*`` | ``\`` | Other functions with|
446+
| | | | | | optimized methods |
447+
+--------------------+-------+-------+-------+-------+---------------------+
448+
| ``Hermitian`` | | | | XY | ``inv``, |
449+
| | | | | | ``sqrtm``, ``expm`` |
450+
+--------------------+-------+-------+-------+-------+---------------------+
451+
| ``Triangular`` | | | XY | XY | ``inv``, ``det`` |
452+
+--------------------+-------+-------+-------+-------+---------------------+
453+
| ``SymTridiagonal`` | X | X | XZ | XY | ``eigmax/min`` |
454+
+--------------------+-------+-------+-------+-------+---------------------+
455+
| ``Tridiagonal`` | X | X | XZ | XY | |
456+
+--------------------+-------+-------+-------+-------+---------------------+
457+
| ``Bidiagonal`` | X | X | XZ | XY | |
458+
+--------------------+-------+-------+-------+-------+---------------------+
459+
| ``Diagonal`` | X | X | XY | XY | ``inv``, ``det``, |
460+
| | | | | | ``logdet``, ``/`` |
461+
+--------------------+-------+-------+-------+-------+---------------------+
462+
463+
Legend:
464+
465+
+---+---------------------------------------------------------------+
466+
| X | An optimized method for matrix-matrix operations is available |
467+
+---+---------------------------------------------------------------+
468+
| Y | An optimized method for matrix-vector operations is available |
469+
+---+---------------------------------------------------------------+
470+
| Z | An optimized method for matrix-scalar operations is available |
471+
+---+---------------------------------------------------------------+
472+
473+
Matrix factorizations
474+
---------------------
475+
476+
+--------------------+-------------------------------------+-----------------------------+
477+
| Matrix type | Eigensystems | Singular values and vectors |
478+
| +---------+-------------+-------------+---------+-------------------+
479+
| | ``eig`` | ``eigvals`` | ``eigvecs`` | ``svd`` | ``svdvals`` |
480+
+--------------------+---------+-------------+-------------+---------+-------------------+
481+
| ``Hermitian`` | | ABC | | | |
482+
| | | | | | |
483+
+--------------------+---------+-------------+-------------+---------+-------------------+
484+
| ``Triangular`` | | | | | |
485+
+--------------------+---------+-------------+-------------+---------+-------------------+
486+
| ``SymTridiagonal`` | A | ABC | AD | | |
487+
+--------------------+---------+-------------+-------------+---------+-------------------+
488+
| ``Tridiagonal`` | | | | | |
489+
+--------------------+---------+-------------+-------------+---------+-------------------+
490+
| ``Bidiagonal`` | | | | A | A |
491+
+--------------------+---------+-------------+-------------+---------+-------------------+
492+
| ``Diagonal`` | | A | | | |
493+
| | | | | | |
494+
+--------------------+---------+-------------+-------------+---------+-------------------+
495+
496+
Legend:
497+
498+
+---+-----------------------------------------------------------------------------------------------------------------------------------+------------------------+
499+
| A | An optimized method to find all the characteristic values and/or vectors is available | e.g. ``eigvals(M)`` |
500+
+---+-----------------------------------------------------------------------------------------------------------------------------------+------------------------+
501+
| B | An optimized method to find the ``il``:sup:`th` through the ``ih``:sup:`th` characteristic values are available | ``eigvals(M, il, ih)`` |
502+
+---+-----------------------------------------------------------------------------------------------------------------------------------+------------------------+
503+
| C | An optimized method to find the characteristic values in the interval [``vl``, ``vh``] is available | ``eigvals(M, vl, vh)`` |
504+
+---+-----------------------------------------------------------------------------------------------------------------------------------+------------------------+
505+
| D | An optimized method to find the characteristic vectors corresponding to the characteristic values ``x=[x1, x2,...]`` is available | ``eigvecs(M, x)`` |
506+
+---+-----------------------------------------------------------------------------------------------------------------------------------+------------------------+
507+
508+
509+
388510
******************
389511
Sparse Matrices
390512
******************
@@ -399,13 +521,12 @@ compared to performing the same operations on a dense matrix.
399521
Compressed Sparse Column (CSC) Storage
400522
--------------------------------------
401523

402-
In julia, sparse matrices are stored in the `Compressed Sparse Column
524+
In Julia, sparse matrices are stored in the `Compressed Sparse Column
403525
(CSC) format
404-
<http://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_column_.28CSC_or_CCS.29>`_. Julia
405-
sparse matrices have the type ``SparseMatrixCSC{Tv,Ti}``, where ``Tv``
526+
<http://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_column_.28CSC_or_CCS.29>`_.
527+
Julia sparse matrices have the type ``SparseMatrixCSC{Tv,Ti}``, where ``Tv``
406528
is the type of the nonzero values, and ``Ti`` is the integer type for
407-
storing column pointers and row indices.
408-
::
529+
storing column pointers and row indices.::
409530

410531
type SparseMatrixCSC{Tv,Ti<:Integer} <: AbstractSparseMatrix{Tv,Ti}
411532
m::Int # Number of rows
@@ -502,6 +623,57 @@ matrices. Indexing of, assignment into, and concatenation of sparse
502623
matrices work in the same way as dense matrices. Indexing operations,
503624
especially assignment, are expensive, when carried out one element at
504625
a time. In many cases it may be better to convert the sparse matrix
505-
into ``(I,J,V)`` format using ``find_nzs``, manipulate the nonzeros or
626+
into ``(I,J,V)`` format using ``find_nzs``, manipulate the non-zeroes or
506627
the structure in the dense vectors ``(I,J,V)``, and then reconstruct
507628
the sparse matrix.
629+
630+
Correspondence of dense and sparse methods
631+
------------------------------------------
632+
The following table gives a correspondence between built-in methods on sparse
633+
matrices and their corresponding methods on dense matrix types. In general,
634+
methods that generate sparse matrices differ from their dense counterparts in
635+
that the resulting matrix follows the same sparsity pattern as a given sparse
636+
matrix ``S``, or that the resulting sparse matrix has density ``d``, i.e. each
637+
matrix element has a probability ``d`` of being non-zero.
638+
639+
Details can be found in the :ref:`stdlib-sparse` section of the standard library
640+
reference.
641+
642+
+-----------------------+-------------------+----------------------------------------+
643+
| Sparse | Dense | Description |
644+
+-----------------------+-------------------+----------------------------------------+
645+
| ``spzeros(m,n)`` | ``zeros(m,n)`` | Creates a *m*-by-*n* matrix of zeros. |
646+
| | | (``spzeros(m,n)`` is empty.) |
647+
+-----------------------+-------------------+----------------------------------------+
648+
| ``spones(S)`` | ``ones(m,n)`` | Creates a matrix filled with ones. |
649+
| | | Unlike the dense version, ``spones`` |
650+
| | | has the same sparsity pattern as *S*. |
651+
+-----------------------+-------------------+----------------------------------------+
652+
| ``speye(n)`` | ``eye(n)`` | Creates a *n*-by-*n* identity matrix. |
653+
+-----------------------+-------------------+----------------------------------------+
654+
| ``dense(S)`` | ``sparse(A)`` | Interconverts between dense |
655+
| ``full(S)`` | | and sparse formats. |
656+
+-----------------------+-------------------+----------------------------------------+
657+
| ``sprand(m,n,d)`` | ``rand(m,n)`` | Creates a *n*-by-*n* random matrix (of |
658+
| | | density *d*) with iid non-zero elements|
659+
| | | distributed uniformly on the |
660+
| | | interval [0, 1]. |
661+
+-----------------------+-------------------+----------------------------------------+
662+
| ``sprandn(m,n,d)`` | ``randn(m,n)`` | Creates a *n*-by-*n* random matrix (of |
663+
| | | density *d*) with iid non-zero elements|
664+
| | | distributed according to the standard |
665+
| | | normal (Gaussian) distribution. |
666+
+-----------------------+-------------------+----------------------------------------+
667+
| ``sprandn(m,n,d,X)`` | ``randn(m,n,X)`` | Creates a *n*-by-*n* random matrix (of |
668+
| | | density *d*) with iid non-zero elements|
669+
| | | distributed according to the *X* |
670+
| | | distribution. (Requires the |
671+
| | | ``Distributions`` package.) |
672+
+-----------------------+-------------------+----------------------------------------+
673+
| ``sprandbool(m,n,d)`` | ``randbool(m,n)`` | Creates a *n*-by-*n* random matrix (of |
674+
| | | density *d*) with non-zero ``Bool`` |
675+
| | | elements with probability *d* (*d* =0.5|
676+
| | | for ``randbool``.) |
677+
+-----------------------+-------------------+----------------------------------------+
678+
679+

‎doc/stdlib/linalg.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _stdlib-linalg:
2+
13
Linear Algebra
24
--------------
35

‎doc/stdlib/sparse.rst

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
.. _stdlib-sparse:
12

23
Sparse Matrices
34
---------------

0 commit comments

Comments
 (0)