Mercurial > octave-antonio

comparison doc/interpreter/sparse.txi @ 8817:03b7f618ab3d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
include docstrings for new functions in the manual
author John W. Eaton <jwe@octave.org>
date Thu, 19 Feb 2009 15:39:19 -0500
parents cdb4788879b3
children 8463d1a2e544
comparison
equal deleted inserted replaced
8816:a4a8f871be81 8817:03b7f618ab3d
25 25
26 @node Sparse Matrices 26 @node Sparse Matrices
27 @chapter Sparse Matrices 27 @chapter Sparse Matrices
28 28
29 @menu 29 @menu
30 * Basics:: The Creation and Manipulation of Sparse Matrices 30 * Basics:: Creation and Manipulation of Sparse Matrices
31 * Sparse Linear Algebra:: Linear Algebra on Sparse Matrices 31 * Sparse Linear Algebra:: Linear Algebra on Sparse Matrices
32 * Iterative Techniques:: Iterative Techniques applied to Sparse Matrices 32 * Iterative Techniques:: Iterative Techniques
33 * Real Life Example:: Real Life Example of the use of Sparse Matrices 33 * Real Life Example:: Using Sparse Matrices
34 @end menu 34 @end menu
35 35
36 @node Basics, Sparse Linear Algebra, Sparse Matrices, Sparse Matrices 36 @node Basics
37 @section The Creation and Manipulation of Sparse Matrices 37 @section The Creation and Manipulation of Sparse Matrices
38 38
39 The size of mathematical problems that can be treated at any particular 39 The size of mathematical problems that can be treated at any particular
40 time is generally limited by the available computing resources. Both, 40 time is generally limited by the available computing resources. Both,
41 the speed of the computer and its available memory place limitation on 41 the speed of the computer and its available memory place limitation on
54 sparse. It is the purpose of this document to discuss the basics of the 54 sparse. It is the purpose of this document to discuss the basics of the
55 storage and creation of sparse matrices and the fundamental operations 55 storage and creation of sparse matrices and the fundamental operations
56 on them. 56 on them.
57 57
58 @menu 58 @menu
59 * Storage:: Storage of Sparse Matrices 59 * Storage of Sparse Matrices::
60 * Creation:: Creating Sparse Matrices 60 * Creating Sparse Matrices::
61 * Information:: Finding out Information about Sparse Matrices 61 * Information::
62 * Operators and Functions:: Basic Operators and Functions on Sparse Matrices 62 * Operators and Functions::
63 @end menu 63 @end menu
64 64
65 @node Storage, Creation, Basics, Basics 65 @node Storage of Sparse Matrices
66 @subsection Storage of Sparse Matrices 66 @subsection Storage of Sparse Matrices
67 67
68 It is not strictly speaking necessary for the user to understand how 68 It is not strictly speaking necessary for the user to understand how
69 sparse matrices are stored. However, such an understanding will help 69 sparse matrices are stored. However, such an understanding will help
70 to get an understanding of the size of sparse matrices. Understanding 70 to get an understanding of the size of sparse matrices. Understanding
164 the need to sort the elements on the creation of sparse matrices. Having 164 the need to sort the elements on the creation of sparse matrices. Having
165 disordered elements is potentially an advantage in that it makes operations 165 disordered elements is potentially an advantage in that it makes operations
166 such as concatenating two sparse matrices together easier and faster, however 166 such as concatenating two sparse matrices together easier and faster, however
167 it adds complexity and speed problems elsewhere. 167 it adds complexity and speed problems elsewhere.
168 168
169 @node Creation, Information, Storage, Basics 169 @node Creating Sparse Matrices
170 @subsection Creating Sparse Matrices 170 @subsection Creating Sparse Matrices
171 171
172 There are several means to create sparse matrix. 172 There are several means to create sparse matrix.
173 173
174 @table @asis 174 @table @asis
301 oct-files. However, the construction of a sparse matrix from an oct-file 301 oct-files. However, the construction of a sparse matrix from an oct-file
302 is more complex than can be discussed in this brief introduction, and 302 is more complex than can be discussed in this brief introduction, and
303 you are referred to chapter @ref{Dynamically Linked Functions}, to have 303 you are referred to chapter @ref{Dynamically Linked Functions}, to have
304 a full description of the techniques involved. 304 a full description of the techniques involved.
305 305
306 @node Information, Operators and Functions, Creation, Basics 306 @node Information
307 @subsection Finding out Information about Sparse Matrices 307 @subsection Finding out Information about Sparse Matrices
308 308
309 There are a number of functions that allow information concerning 309 There are a number of functions that allow information concerning
310 sparse matrices to be obtained. The most basic of these is 310 sparse matrices to be obtained. The most basic of these is
311 @dfn{issparse} that identifies whether a particular Octave object is 311 @dfn{issparse} that identifies whether a particular Octave object is
419 419
420 @DOCSTRING(gplot) 420 @DOCSTRING(gplot)
421 421
422 @DOCSTRING(treeplot) 422 @DOCSTRING(treeplot)
423 423
424 @node Operators and Functions, , Information, Basics 424 @DOCSTRING(treelayout)
425
426 @node Operators and Functions
425 @subsection Basic Operators and Functions on Sparse Matrices 427 @subsection Basic Operators and Functions on Sparse Matrices
426 428
427 @menu 429 @menu
428 * Functions:: Sparse Functions 430 * Sparse Functions::
429 * ReturnType:: The Return Types of Operators and Functions 431 * Return Types of Operators and Functions::
430 * MathConsiderations:: Mathematical Considerations 432 * Mathematical Considerations::
431 @end menu 433 @end menu
432 434
433 @node Functions, ReturnType, Operators and Functions, Operators and Functions 435 @node Sparse Functions
434 @subsubsection Sparse Functions 436 @subsubsection Sparse Functions
435 437
436 An important consideration in the use of the sparse functions of 438 An important consideration in the use of the sparse functions of
437 Octave is that many of the internal functions of Octave, such as 439 Octave is that many of the internal functions of Octave, such as
438 @dfn{diag}, cannot accept sparse matrices as an input. The sparse 440 @dfn{diag}, cannot accept sparse matrices as an input. The sparse
489 math functions that take a single argument) such as @dfn{abs}, etc 491 math functions that take a single argument) such as @dfn{abs}, etc
490 can accept sparse matrices. The reader is referred to the documentation 492 can accept sparse matrices. The reader is referred to the documentation
491 supplied with these functions within Octave itself for further 493 supplied with these functions within Octave itself for further
492 details. 494 details.
493 495
494 @node ReturnType, MathConsiderations, Functions, Operators and Functions 496 @node Return Types of Operators and Functions
495 @subsubsection The Return Types of Operators and Functions 497 @subsubsection The Return Types of Operators and Functions
496 498
497 The two basic reasons to use sparse matrices are to reduce the memory 499 The two basic reasons to use sparse matrices are to reduce the memory
498 usage and to not have to do calculations on zero elements. The two are 500 usage and to not have to do calculations on zero elements. The two are
499 closely related in that the computation time on a sparse matrix operator 501 closely related in that the computation time on a sparse matrix operator
548 @DOCSTRING(sparse_auto_mutate) 550 @DOCSTRING(sparse_auto_mutate)
549 551
550 Note that the @code{sparse_auto_mutate} option is incompatible with 552 Note that the @code{sparse_auto_mutate} option is incompatible with
551 @sc{Matlab}, and so it is off by default. 553 @sc{Matlab}, and so it is off by default.
552 554
553 @node MathConsiderations, , ReturnType, Operators and Functions 555 @node Mathematical Considerations
554 @subsubsection Mathematical Considerations 556 @subsubsection Mathematical Considerations
555 557
556 The attempt has been made to make sparse matrices behave in exactly the 558 The attempt has been made to make sparse matrices behave in exactly the
557 same manner as there full counterparts. However, there are certain differences 559 same manner as there full counterparts. However, there are certain differences
558 and especially differences with other products sparse implementations. 560 and especially differences with other products sparse implementations.
720 722
721 @DOCSTRING(symamd) 723 @DOCSTRING(symamd)
722 724
723 @DOCSTRING(symrcm) 725 @DOCSTRING(symrcm)
724 726
725 @node Sparse Linear Algebra, Iterative Techniques, Basics, Sparse Matrices 727 @node Sparse Linear Algebra
726 @section Linear Algebra on Sparse Matrices 728 @section Linear Algebra on Sparse Matrices
727 729
728 Octave includes a polymorphic solver for sparse matrices, where 730 Octave includes a polymorphic solver for sparse matrices, where
729 the exact solver used to factorize the matrix, depends on the properties 731 the exact solver used to factorize the matrix, depends on the properties
730 of the sparse matrix itself. Generally, the cost of determining the matrix type 732 of the sparse matrix itself. Generally, the cost of determining the matrix type
838 840
839 @DOCSTRING(eigs) 841 @DOCSTRING(eigs)
840 842
841 @DOCSTRING(svds) 843 @DOCSTRING(svds)
842 844
843 @node Iterative Techniques, Real Life Example, Sparse Linear Algebra, Sparse Matrices 845 @node Iterative Techniques
844 @section Iterative Techniques applied to sparse matrices 846 @section Iterative Techniques applied to sparse matrices
845 847
846 The left division @code{\} and right division @code{/} operators, 848 The left division @code{\} and right division @code{/} operators,
847 discussed in the previous section, use direct solvers to resolve a 849 discussed in the previous section, use direct solvers to resolve a
848 linear equation of the form @code{@var{x} = @var{A} \ @var{b}} or 850 linear equation of the form @code{@var{x} = @var{A} \ @var{b}} or
859 @var{A} \ @var{b}} is solved instead. Typical pre-conditioning matrices 861 @var{A} \ @var{b}} is solved instead. Typical pre-conditioning matrices
860 are partial factorizations of the original matrix. 862 are partial factorizations of the original matrix.
861 863
862 @DOCSTRING(luinc) 864 @DOCSTRING(luinc)
863 865
864 @node Real Life Example, , Iterative Techniques, Sparse Matrices 866 @node Real Life Example
865 @section Real Life Example of the use of Sparse Matrices 867 @section Real Life Example of the use of Sparse Matrices
866 868
867 A common application for sparse matrices is in the solution of Finite 869 A common application for sparse matrices is in the solution of Finite
868 Element Models. Finite element models allow numerical solution of 870 Element Models. Finite element models allow numerical solution of
869 partial differential equations that do not have closed form solutions, 871 partial differential equations that do not have closed form solutions,