scilab/modules/linear_algebra/help/en_US/linear/linsolve.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) 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="linsolve">
  17     <refnamediv>
  18         <refname>linsolve</refname>
  19         <refpurpose>linear equation solver</refpurpose>
  20     </refnamediv>
  21     <refsynopsisdiv>
  22         <title>Syntax</title>
  23         <synopsis>[x0,kerA]=linsolve(A,b [,x0])</synopsis>
  24     </refsynopsisdiv>
  25     <refsection>
  26         <title>Arguments</title>
  27         <variablelist>
  28             <varlistentry>
  29                 <term>A</term>
  30                 <listitem>
  31                     <para>
  32                         a <literal>na x ma</literal> real matrix (possibly sparse)
  33                     </para>
  34                 </listitem>
  35             </varlistentry>
  36             <varlistentry>
  37                 <term>b</term>
  38                 <listitem>
  39                     <para>
  40                         a <literal>na x 1</literal> vector (same row dimension as <literal>A</literal>)
  41                     </para>
  42                 </listitem>
  43             </varlistentry>
  44             <varlistentry>
  45                 <term>x0</term>
  46                 <listitem>
  47                     <para>a real vector</para>
  48                 </listitem>
  49             </varlistentry>
  50             <varlistentry>
  51                 <term>kerA</term>
  52                 <listitem>
  53                     <para>
  54                         a <literal>ma x k</literal> real matrix
  55                     </para>
  56                 </listitem>
  57             </varlistentry>
  58         </variablelist>
  59     </refsection>
  60     <refsection>
  61         <title>Description</title>
  62         <para>
  63             <literal>linsolve</literal>  computes all the solutions to <literal> A*x+b=0</literal>.
  64         </para>
  65         <para>
  66             <literal>x0</literal> is a particular solution (if any) and <literal> kerA= </literal>nullspace
  67             of <literal>A</literal>. Any <literal>x=x0+kerA*w</literal> with arbitrary <literal>w</literal> satisfies
  68             <literal> A*x+b=0</literal>.
  69         </para>
  70         <para>
  71             If compatible <literal>x0</literal> is given on entry, <literal>x0</literal> is returned. If not
  72             a compatible <literal>x0</literal>, if any, is returned.
  73         </para>
  74     </refsection>
  75     <refsection>
  76         <title>Examples</title>
  77         <programlisting role="example"><![CDATA[
  78 A=rand(5,3)*rand(3,8);
  79 b=A*ones(8,1);[x,kerA]=linsolve(A,b);A*x+b   //compatible b
  80 b=ones(5,1);[x,kerA]=linsolve(A,b);A*x+b   //uncompatible b
  81 A=rand(5,5);[x,kerA]=linsolve(A,b), -inv(A)*b  //x is unique
  82
  83 // Benchmark with other linear sparse solver:
  84 [A,descr,ref,mtype] = ReadHBSparse(SCI+"/modules/umfpack/examples/bcsstk24.rsa");
  85
  86 b = zeros(size(A,1),1);
  87
  88 tic();
  89 res = umfpack(A,'\',b);
  90 mprintf('\ntime needed to solve the system with umfpack: %.3f\n',toc());
  91
  92 tic();
  93 res = linsolve(A,b);
  94 mprintf('\ntime needed to solve the system with linsolve: %.3f\n',toc());
  95
  96 tic();
  97 res = A\b;
  98 mprintf('\ntime needed to solve the system with the backslash operator: %.3f\n',toc());
  99  ]]></programlisting>
 100     </refsection>
 101     <refsection role="see also">
 102         <title>See also</title>
 103         <simplelist type="inline">
 104             <member>
 105                 <link linkend="inv">inv</link>
 106             </member>
 107             <member>
 108                 <link linkend="pinv">pinv</link>
 109             </member>
 110             <member>
 111                 <link linkend="colcomp">colcomp</link>
 112             </member>
 113             <member>
 114                 <link linkend="im_inv">im_inv</link>
 115             </member>
 116             <member>
 117                 <link linkend="umfpack">umfpack</link>
 118             </member>
 119             <member>
 120                 <link linkend="backslash">backslash</link>
 121             </member>
 122         </simplelist>
 123     </refsection>
 124 </refentry>