<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2006-2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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="clean">
    <refnamediv>
        <refname>clean</refname>
        <refpurpose>cleans matrices (round to zero small entries)</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
          B = clean(A)
          B = clean(A, epsa)
          B = clean(A, epsa, epsr)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>A</term>
                <listitem>
                    <para>
                      scalar, vector, matrix or hypermatrix of decimal numbers or of
                      complex numbers, in dense or sparse encoding, or of polynomials or
                      rationals with real or complex coefficients.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>epsa, epsr</term>
                <listitem>
                    <para>
                        positive real numbers: Cleaning tolerances. Both default values are
                       10<superscript>-10</superscript>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            This function sets to 0 all the elements of <varname>A</varname>
            with absolute value &lt;=<varname>epsa</varname> or relative value &lt;=<varname>epsr</varname>
            (relative w.r.t. to max(abs(A)), ignoring %inf and %nan values of <varname>A</varname>).
        </para>
        <para>
            For an array of polynomials or of rationals, clean() applies in the same way to the
            whole set of their coefficients.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
m = grand(3,5,"uin",1,9) .* 10.^grand(3,5,"uin",-16,1)
clean(m)
clean(m, 1e-7)
     ]]></programlisting>
   <screen><![CDATA[
--> m = grand(3,5,"uin",1,9) .* 10.^grand(3,5,"uin",-16,1)
 m  =
   5.000D-08   5.          0.8         7.000D-08   4.000D-11
   0.00007     7.          4.000D-09   6.000D-13   2.000D-16
   2.000D-08   1.000D-14   1.          8.          0.7

--> clean(m)
 ans  =
   5.000D-08   5.   0.8         7.000D-08   0.
   0.00007     7.   4.000D-09   0.          0.
   2.000D-08   0.   1.          8.          0.7

--> clean(m, 1e-7)
 ans  =
   0.        5.   0.8   0.   0.
   0.00007   7.   0.    0.   0.
   0.        0.   1.    8.   0.7
]]></screen>
        <para/>
        <para>
            <emphasis role="bold">For rationals:</emphasis>
        </para>
        <programlisting role="example"><![CDATA[
x = poly(0,'x');
w = [3+2*x, 2+x; 3+x, 2-x]/5
r = w * inv(w)
clean(r)
     ]]></programlisting>
   <screen><![CDATA[
--> w = [3+2*x, 2+x; 3+x, 2-x]/5
 w  =
   0.6 +0.4x   0.4 +0.2x
   0.6 +0.2x   0.4 -0.2x

--> r = w * inv(w)
 r  =
                                                                2
   -3.140D-16 + x                        -1.110D-15 + 3.331D-16x
   ---------------                       ------------------------
                                                           2
         x                                   1.3333333x + x
                                      2                             2
   1.110D-15 - 2.220D-16x - 5.551D-17x   -1.110D-15 + 1.3333333x + x
   ------------------------------------  ----------------------------
                           2                                 2
             1.3333333x + x                    1.3333333x + x

--> clean(r)
 ans  =
   1   0
   --  --
   1   1

   0   1
   --  --
   1   1
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="percenteps">%eps</link>
            </member>
            <member>
                <link linkend="cond">cond</link>
            </member>
            <member>
                <link linkend="nearfloat">nearfloat</link>
            </member>
            <member>
                <link linkend="number_properties">number_properties</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
