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. If many values are given for same position, theses values are summed.
  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>