3243824a39bb4a190f670bf66f879f66c80caf73
[scilab.git] / scilab / modules / sparse / help / en_US / sparseconvert / sparse.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) XXXX-2008 - INRIA
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19         xml:lang="en" xml:id="sparse">
20     <refnamediv>
21         <refname>sparse</refname>
22         <refpurpose>sparse matrix definition</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             sp = sparse(X)
28             sp = sparse(ij, v)
29             sp = sparse(ij, v, mn)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>X</term>
37                 <listitem>
38                     <para>real or complex or boolean full (or sparse) matrix</para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>ij</term>
43                 <listitem>
44                     <para>two columns integer matrix (indices of non-zeros entries)</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>v</term>
49                 <listitem>
50                     <para>vector</para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>mn</term>
55                 <listitem>
56                     <para>integer vector with two entries (row-dimension, column-dimension)</para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>sp</term>
61                 <listitem>
62                     <para>sparse matrix</para>
63                 </listitem>
64             </varlistentry>
65         </variablelist>
66     </refsection>
67     <refsection>
68         <title>Description</title>
69         <para>
70             <literal>sparse</literal> is used to build a sparse matrix. Only non-zero entries
71             are stored.
72         </para>
73         <para>
74             <literal>sp = sparse(X)</literal>  converts a full matrix to sparse form by
75             squeezing out any zero elements. (If <literal>X</literal> is already sparse
76             <literal>sp</literal> is <literal>X</literal>).
77         </para>
78         <para>
79             <literal>sp=sparse(ij,v [,mn])</literal>  builds an <literal>mn(1)</literal>-by-<literal>mn(2)</literal>
80             sparse matrix with <literal>sp(ij(k,1),ij(k,2))=v(k)</literal>.
81             <literal>ij</literal> and <literal>v</literal> must have the same column dimension.
82             If optional <literal>mn</literal> parameter is not given the <literal>sp</literal>
83             matrix dimensions are the max value of <literal>ij(:,1)</literal> and <literal>ij(:,2)</literal>
84             respectively.
85         </para>
86         <para>
87             Operations (concatenation, addition, etc,) with sparse matrices are
88             made using the same syntax as for full matrices.
89         </para>
90         <para>
91             Elementary functions are also available (<literal>abs,maxi,sum,diag,...</literal>)
92             for sparse matrices.
93         </para>
94         <para>
95             Mixed operations (full-sparse) are allowed. Results are full or sparse
96             depending on the operations.
97         </para>
98         <para>
99             Note : Any operation involving dense matrices of the same size, either as argument (e.g. <literal>sp=sparse(d)</literal>)
100             or as result (e.g.  <literal>d= sp + 1.</literal>) is provided for convenience purposes but should of course be avoided.
101             Furthermore, random access to elements (<literal>sp(r,c)</literal>), especially for insertions, is not efficient, so
102             any performance-constrained access should be done in batches with <link linkend="spget">spget</link> for read access
103             and the three arguments constructor <literal>sp=sparse(ij, v, mn)</literal> for write access.
104         </para>
105     </refsection>
106     <refsection>
107         <title>Examples</title>
108         <programlisting role="example"><![CDATA[
109 sp = sparse([1,2;4,5;3,10],[1,2,3])
110 size(sp)
111
112 x = rand(2,2);
113 abs(x) - full(abs(sparse(x)))
114
115 // sparse constructor taking a single dense matrix
116 // removes the zeros.
117 dense = [0., 1., 0., 0., 0.,
118 1., 0., 2., 0., 0.
119 0., 0., 0., 0., 0.
120 0., 0., 0., 0., -0.5];
121 sp = sparse(dense)
122
123 // complex matrices are also supported
124 sp = sparse(dense*(1+2*%i))
125
126 // for boolean matrices, the boolean sparse matrix
127 // only stores true values (and removes false values).
128 dense = [%F, %F, %T, %F, %F
129 %T, %F, %F, %F, %F
130 %F, %F, %F, %F, %F
131 %F, %F, %F, %F, %T];
132 sp = sparse(dense)
133 ]]></programlisting>
134     </refsection>
135     <refsection role="see also">
136         <title>See also</title>
137         <simplelist type="inline">
138             <member>
139                 <link linkend="full">full</link>
140             </member>
141             <member>
142                 <link linkend="spget">spget</link>
143             </member>
144             <member>
145                 <link linkend="sprand">sprand</link>
146             </member>
147             <member>
148                 <link linkend="speye">speye</link>
149             </member>
150             <member>
151                 <link linkend="diag">diag</link>
152             </member>
153             <member>
154                 <link linkend="toeplitz">toeplitz</link>
155             </member>
156         </simplelist>
157     </refsection>
158 </refentry>