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