<?xml version="1.0" encoding="UTF-8"?>
<refentry version="5.0-subset Scilab" xml:id="gf_spmat" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:html="http://www.w3.org/1999/xhtml"
          xmlns:db="http://docbook.org/ns/docbook">
  <refnamediv>
    <refname>gf_spmat</refname>
    <refpurpose>  Create a new sparse matrix in getfem++ format. These sparse matrix can be stored as CSC (compressed column
  sparse), which is the format used by Matlab, or they can be stored as WSC
  (internal format to getfem). The CSC matrices are not writable (it would
  be very inefficient), but they are optimized for multiplication with
  vectors, and memory usage. The WSC are writable, they are very fast with
  respect to random read/write operation. However their memory overhead is
  higher than CSC matrices, and they are a little bit slower for
  matrix-vector multiplications.

  By default, all newly created matrices are build as WSC matrices. This can
  be changed later with <literal></literal>gf_spmat_set(spmat S, 'to_csc',...)<literal></literal>, or may be changed
  automatically by getfem (for example <literal></literal>gf_linsolve()<literal></literal> converts the
  matrices to CSC).

  The matrices may store REAL or COMPLEX values.
</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>

    <synopsis>SM = gf_spmat('empty', int m [, int n])</synopsis>
    <synopsis>SM = gf_spmat('copy', mat K [,  I [,  J]])</synopsis>
    <synopsis>SM = gf_spmat('identity', int n)</synopsis>
    <synopsis>SM = gf_spmat('mult', spmat A, spmat B)</synopsis>
    <synopsis>SM = gf_spmat('add', spmat A, spmat B)</synopsis>
    <synopsis>SM = gf_spmat('diag', mat D [, ivec E [, int n [,int m]]])</synopsis>
    <synopsis>SM = gf_spmat('load','hb'|'harwell-boeing'|'mm'|'matrix-market', string filename)</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>
    <para>General constructor for spmat objects.</para>

    <para>  Create a new sparse matrix in getfem++ format. These sparse matrix can be stored as CSC (compressed column
  sparse), which is the format used by Matlab, or they can be stored as WSC
  (internal format to getfem). The CSC matrices are not writable (it would
  be very inefficient), but they are optimized for multiplication with
  vectors, and memory usage. The WSC are writable, they are very fast with
  respect to random read/write operation. However their memory overhead is
  higher than CSC matrices, and they are a little bit slower for
  matrix-vector multiplications.

  By default, all newly created matrices are build as WSC matrices. This can
  be changed later with <literal></literal>gf_spmat_set(spmat S, 'to_csc',...)<literal></literal>, or may be changed
  automatically by getfem (for example <literal></literal>gf_linsolve()<literal></literal> converts the
  matrices to CSC).

  The matrices may store REAL or COMPLEX values.
</para>
  </refsection>

  <refsection>
    <title>Command list</title>

    <itemizedlist>
    <listitem>
    <para><literal>SM = gf_spmat('empty', int m [, int n])</literal></para>

    <para>         Create a new empty (i.e. full of zeros) sparse matrix, of dimensions
      <literal>m x n</literal>. If <literal>n</literal> is omitted, the matrix dimension is <literal>m x m</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>SM = gf_spmat('copy', mat K [,  I [,  J]])</literal></para>

    <para>         Duplicate a matrix <literal>K</literal> (which might be a spmat). If index <literal>I</literal> and/or <literal>J</literal> are given, the matrix will
      be a submatrix of <literal>K</literal>. For example::

        
        m = gf_spmat('copy', sprand(50,50,.1), 1:40, [6 7 8 3 10])
        

      will return a 40x5 matrix.
    </para>
    </listitem>

    <listitem>
    <para><literal>SM = gf_spmat('identity', int n)</literal></para>

    <para>          Create a <literal>n x n</literal> identity matrix.
    </para>
    </listitem>

    <listitem>
    <para><literal>SM = gf_spmat('mult', spmat A, spmat B)</literal></para>

    <para>          Create a sparse matrix as the product of the sparse matrices <literal>A</literal> and
       <literal>B</literal>. It requires that <literal>A</literal> and <literal>B</literal> be both real or both complex, you
       may have to use <literal></literal>gf_spmat_set(spmat S, 'to_complex')<literal></literal> 
    </para>
    </listitem>

    <listitem>
    <para><literal>SM = gf_spmat('add', spmat A, spmat B)</literal></para>

    <para>          Create a sparse matrix as the sum of the sparse matrices <literal>A</literal> and <literal>B</literal>.
       Adding a real matrix with a complex matrix is possible.
    </para>
    </listitem>

    <listitem>
    <para><literal>SM = gf_spmat('diag', mat D [, ivec E [, int n [,int m]]])</literal></para>

    <para>          Create a diagonal matrix. If <literal>E</literal> is given, <literal>D</literal> might be a matrix and
       each column of <literal>E</literal> will contain the sub-diagonal number that will be
       filled with the corresponding column of <literal>D</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>SM = gf_spmat('load','hb'|'harwell-boeing'|'mm'|'matrix-market', string filename)</literal></para>

    <para>         Read a sparse matrix from an Harwell-Boeing or a Matrix-Market file
      .
    </para>
    </listitem>

    </itemizedlist>
  </refsection>

  <refsection>
    <title>See Also</title>
    <simplelist type="inline">
      <member><link linkend="getfem_types">getfem types</link></member>
    </simplelist>
  </refsection>

  <refsection>
    <title>Authors</title>
    <para>Y. Collette</para>
  </refsection>

</refentry>
