Add nthroot function 65/6865/8
Adeline CARNIS [Tue, 3 Apr 2012 15:44:49 +0000 (17:44 +0200)]
Change-Id: I70b732fb2b8cbe064a80b45286775decd31da0f6

SEP/INDEX
SEP/SEP_078_nthroot.odt [new file with mode: 0644]
scilab/CHANGES_5.4.X
scilab/modules/elementary_functions/help/en_US/nthroot.xml [new file with mode: 0644]
scilab/modules/elementary_functions/macros/nthroot.sci [new file with mode: 0644]
scilab/modules/elementary_functions/tests/unit_tests/nthroot.dia.ref [new file with mode: 0644]
scilab/modules/elementary_functions/tests/unit_tests/nthroot.tst [new file with mode: 0644]

index aadd06b..6a4fb67 100644 (file)
--- a/SEP/INDEX
+++ b/SEP/INDEX
@@ -74,3 +74,4 @@ SEP #074: Atoms configuration files management
 SEP #075: New dec2base function
 SEP #076: atomsCheckModule function
 SEP #077: atomsQuit function
+SEP #078: nthroot function
\ No newline at end of file
diff --git a/SEP/SEP_078_nthroot.odt b/SEP/SEP_078_nthroot.odt
new file mode 100644 (file)
index 0000000..f2b2dea
Binary files /dev/null and b/SEP/SEP_078_nthroot.odt differ
index 62c39d3..d766e24 100644 (file)
@@ -151,6 +151,8 @@ Elementary functions
 
 * Bug #10835 fixed - Typo that made the 'atanm' function unusable fixed.
 
+* nthroot function added (See SEP #78).
+
 
 CLI console:
 ============
@@ -442,6 +444,8 @@ Bug fixes
 
 * Bug #9424 fixed - gettext("") did not return "".
 
+* Bug #9549 fixed - Add nthroot function.
+
 * Bug #9572 fixed - assert_checkerror did not check multi lines errors.
 
 * Bug #9643 fixed - genetic algorithms demo was not vectorized.
@@ -874,7 +878,7 @@ New Functions
 
 * The damp function in CACSD module computes the natural pulsation
   and damping factor of linear dynamical systems.
-
+  
 
 Optimization
 =============
diff --git a/scilab/modules/elementary_functions/help/en_US/nthroot.xml b/scilab/modules/elementary_functions/help/en_US/nthroot.xml
new file mode 100644 (file)
index 0000000..129fd08
--- /dev/null
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2008 - INRIA
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="nthroot" xml:lang="en">
+  <info>
+    <pubdate>$LastChangedDate$</pubdate>
+  </info>
+  <refnamediv>
+    <refname>nthroot</refname>
+    <refpurpose>Real nth root of real numbers</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+    <synopsis>y=ntrhoot(x,n)</synopsis>
+  </refsynopsisdiv>
+  <refsection>
+    <title>Arguments</title>
+    <variablelist>
+      <varlistentry>
+        <term>x</term>
+        <listitem>
+         <para>real scalar or vector/matrix</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+       <variablelist>
+      <varlistentry>
+        <term>n</term>
+        <listitem>
+         <para>real scalar</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+  <refsection>
+    <title>Description</title>
+    <para>
+      <literal>nthroot(x,n)</literal> is the real vector/matrix of the nth root of the
+      <literal>x</literal> elements. If <literal>x</literal> has negative elements, <literal>n</literal> must be an odd.
+    </para>
+  </refsection>
+  <refsection>
+    <title>Examples</title>
+    <programlisting role="example"><![CDATA[ 
+       nthroot(2,3)    
+       nthroot(-2,3)   
+       nthroot(-2,-3)
+       nthroot(2,-3)
+ ]]></programlisting>
+  </refsection>
+  <refsection role="see also">
+    <title>See Also</title>
+    <simplelist type="inline">
+      <member>
+        <link linkend="hat">hat</link>
+      </member>
+         <member>
+        <link linkend="sqrt">sqrt</link>
+      </member>
+      <member>
+        <link linkend="sqrtm">sqrtm</link>
+      </member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/elementary_functions/macros/nthroot.sci b/scilab/modules/elementary_functions/macros/nthroot.sci
new file mode 100644 (file)
index 0000000..b5fc999
--- /dev/null
@@ -0,0 +1,64 @@
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+// Copyright (C) Scilab Enterprises - 2012 - Adeline CARNIS
+//
+// This file must be used under the terms of the CeCILL.
+// This source file is licensed as described in the file COPYING, which
+// you should have received as part of this distribution.  The terms
+// are also available at
+// http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+
+function y = nthroot(x,n)
+    
+    rhs = argn(2);
+    
+    // if the number of input arguments is wrong
+    if rhs <> 2 then
+        error(msprintf(gettext("%s: Wrong number of input argument(s): %d expected.\n"), "nthroot", 2));
+    end
+    
+    // if x or n are not real
+    if ((typeof(x) <> "constant" | ~isreal(x)) | (typeof(n) <> "constant" | ~isreal(n))) then
+        error(msprintf(gettext("%s: Wrong type for input argument(s) %d: real arguments expected.\n"),"nthroot",2));
+    end
+    
+    // if n is not scalar
+    if (size(n,"*")~=1) then
+        error(msprintf(gettext("%s: Wrong type for input argument(s) %d: n must be a scalar.\n"),"nthroot",1));
+    end
+        
+    reste = modulo(n,2);
+    y = x;
+    
+    // if n = %nan and x is positive then y = %nan
+    if (isnan(n) & or(x >= 0)) then
+        y(find(x>=0)) = %nan;
+    elseif (x==[]) then
+        y = [];
+    elseif (n==0 & (x>=0 | isnan(x))) then
+        // if n = 0 and x = 1 or x = %nan then y = %nan
+        y(find((x==1 | isnan(x)))) = %nan;
+        // if n = 0 and x>1 then y = %inf
+        y(find(x>1)) = %inf;
+        // if n = 0 and x = %eps then y = 0
+        y(find(x==%eps)) = 0;
+    elseif (or (or(x(:)<0) & (n~=fix(n) | reste ==0))) then
+        error(msprintf(gettext("%s: If x is negative, n must be an odd integer\n"),"nthroot"));
+        // if n ~=0 and n ~= %nan
+    elseif (n~=0 & ~isnan(n)) then
+        //if x = 0 and n is negative and n i~= %nan
+        [m1,m2] = size(x(find(x==0 & n<0 & ~isinf(n))));
+        y(find(x==0 & n<0 & ~isinf(n))) = (x(find(x==0 & n<0 & ~isinf(n)))+ones(m1,m2)) .*%inf;
+        //if x = 0 and n is positive and n ~= %nan
+        y(find(x==0 & (n>0 |isinf(n)))) = x(find(x==0 & (n>0 |isinf(n)))).^(1 ./n);
+        // if x is positive
+        y(find(x>0)) = x(find(x>0)).^(1 ./n);
+        // if x is negative
+        y(find(x<0)) = sign(x(find(x<0))).*(abs(x(find(x<0)))).^(1 ./n);
+    end    
+    
+     
+endfunction
+
+
+
+    
\ No newline at end of file
diff --git a/scilab/modules/elementary_functions/tests/unit_tests/nthroot.dia.ref b/scilab/modules/elementary_functions/tests/unit_tests/nthroot.dia.ref
new file mode 100644 (file)
index 0000000..b95c54c
--- /dev/null
@@ -0,0 +1,150 @@
+// =============================================================================
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+// Copyright (C) 2012 - DIGITEO - Adeline CARNIS
+//
+//  This file is distributed under the same license as the Scilab package.
+// =============================================================================
+// <-- JVM NOT MANDATORY -->
+// unit tests for nthroot() function 
+// =============================================================================
+// 1. Interface
+// ============
+assert_checkfalse(execstr("nthroot()"   ,"errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot : Nombre erroné d'argument(s) d'entrée : 2 attendu.   
+assert_checkfalse(execstr("nthroot(1)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot : Nombre erroné d'argument(s) d'entrée : 2 attendu.   
+assert_checkfalse(execstr("nthroot(%i,1)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: Wrong type for input argument(s) 2: real arguments expected.  
+assert_checkfalse(execstr("nthroot(%t,1)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: Wrong type for input argument(s) 2: real arguments expected.  
+assert_checkfalse(execstr("nthroot(3,[])","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: Wrong type for input argument(s) 1: n must be a scalar.   
+assert_checkfalse(execstr("nthroot(-2,%nan)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: If x is negative, n must be an odd integer   
+assert_checkfalse(execstr("nthroot(-2,%eps)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: If x is negative, n must be an odd integer   
+assert_checkfalse(execstr("nthroot(-3,6)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: If x is negative, n must be an odd integer   
+assert_checkfalse(execstr("nthroot(-3,0)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: If x is negative, n must be an odd integer   
+assert_checkfalse(execstr("nthroot(-%inf,-2)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: If x is negative, n must be an odd integer   
+assert_checkfalse(execstr("nthroot(-2,-2)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: If x is negative, n must be an odd integer   
+assert_checkfalse(execstr("nthroot(-2,2)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+ ans  =
+ nthroot: If x is negative, n must be an odd integer   
+// 2. Singular Values
+// ==================
+assert_checkalmostequal(nthroot(2,-2),0.7071068, 1.e-5);
+assert_checkalmostequal(nthroot(2,2),1.4142136, 1.e-5);
+assert_checkalmostequal(nthroot(%eps,3),0.0000061, 1.e-2);
+assert_checkalmostequal(nthroot([1 2],2),[1 1.4142136], 1.e-5);
+assert_checkequal(nthroot(-2,%inf),-1);
+assert_checkequal(nthroot(3,%inf),1);
+assert_checkequal(nthroot(3,-%inf),1);
+assert_checkequal(nthroot(-3,%inf),-1);
+assert_checkequal(nthroot(3,%nan),%nan);
+assert_checkequal(nthroot(3,-%nan),%nan);
+assert_checkequal(nthroot(3,%eps),%inf);
+assert_checkequal(nthroot(3,-%eps),0);
+assert_checkequal(nthroot(3,0),%inf);
+assert_checkequal(nthroot(1,0),%nan);
+assert_checkequal(nthroot([1 2],%inf),[1 1]);
+assert_checkequal(nthroot([1 2],%nan),[%nan %nan]);
+assert_checkequal(nthroot([1 2],%eps),[1 %inf]);
+assert_checkequal(nthroot([1 2],0),[%nan %inf]);
+assert_checkequal(nthroot(0,0),0);
+assert_checkequal(nthroot(0,7),0);
+assert_checkequal(nthroot(0,-7),%inf);
+assert_checkequal(nthroot(0,%inf),1);
+assert_checkequal(nthroot(0,-%inf),1);
+assert_checkequal(nthroot(0,%nan),%nan);
+assert_checkequal(nthroot(0,%eps),0);
+assert_checkequal(nthroot(0,-%eps),%inf);
+assert_checkequal(nthroot([0;-1],%inf),[1;-1]);
+assert_checkequal(nthroot([0;1],0),[0;%nan]);
+// 3. Empty Matrix
+//==================
+assert_checkequal(nthroot([],-2),[]);
+assert_checkequal(nthroot([],3),[]);
+assert_checkequal(nthroot([],%nan),[]);
+assert_checkequal(nthroot([],%inf),[]);
+assert_checkequal(nthroot([],-%inf),[]);
+assert_checkequal(nthroot([],%eps),[]);
+assert_checkequal(nthroot([],-%eps),[]);
+assert_checkequal(nthroot([],0),[]);
+// 4. Limit Values
+// ================
+assert_checkequal(nthroot(-%inf,-7),0);
+assert_checkequal(nthroot(-%inf,7),-%inf);
+assert_checkequal(nthroot(%inf,-7),0);
+assert_checkequal(nthroot(%inf,7),%inf);
+assert_checkequal(nthroot(%inf,%inf),1);
+assert_checkequal(nthroot(%inf,-%inf),1);
+assert_checkequal(nthroot(-%inf,%inf),-1);
+assert_checkequal(nthroot(-%inf,-%inf),-1);
+assert_checkequal(nthroot(%inf,%inf),1);
+assert_checkequal(nthroot(%inf,%nan),%nan);
+assert_checkequal(nthroot(%inf,%eps),%inf);
+assert_checkequal(nthroot(%inf,-%eps),0);
+assert_checkequal(nthroot(%inf,0),%inf);
+assert_checkequal(nthroot([%inf;%nan],3),[%inf;%nan]);
+assert_checkequal(nthroot([%inf;%nan],%nan),[%nan;%nan]);
+assert_checkequal(nthroot([%inf;%nan],0),[%inf;%nan]);
+assert_checkequal(nthroot([%inf;%eps],%eps),[%inf;0]);
+assert_checkequal(nthroot([%inf;%eps],%nan),[%nan;%nan]);
+assert_checkequal(nthroot([%inf;1],0),[%inf;%nan]);
+// 5. Not A Number
+// =================
+assert_checkequal(nthroot(%nan,-2),%nan);
+assert_checkequal(nthroot(%nan,%inf),%nan);
+assert_checkequal(nthroot(%nan,-%inf),%nan);
+assert_checkequal(nthroot(%nan,-%eps),%nan);
+assert_checkequal(nthroot(%nan,0),%nan);
+// 6. X = %eps
+// ===========
+assert_checkequal(nthroot(%eps,%inf),1);
+assert_checkequal(nthroot(%eps,-%inf),1);
+assert_checkequal(nthroot(-%eps,%inf),-1);
+assert_checkequal(nthroot(-%eps,-%inf),-1);
+assert_checkequal(nthroot(%eps,%inf),1);
+assert_checkequal(nthroot(%eps,%nan),%nan);
+assert_checkequal(nthroot(%eps,%eps),0);
+assert_checkequal(nthroot(%eps,-%eps),%inf);
+assert_checkequal(nthroot(%eps,0),0);
diff --git a/scilab/modules/elementary_functions/tests/unit_tests/nthroot.tst b/scilab/modules/elementary_functions/tests/unit_tests/nthroot.tst
new file mode 100644 (file)
index 0000000..758434a
--- /dev/null
@@ -0,0 +1,128 @@
+// =============================================================================
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+// Copyright (C) 2012 - DIGITEO - Adeline CARNIS
+//
+//  This file is distributed under the same license as the Scilab package.
+// =============================================================================
+
+// <-- JVM NOT MANDATORY -->
+
+// unit tests for nthroot() function 
+// =============================================================================
+
+// 1. Interface
+// ============
+assert_checkfalse(execstr("nthroot()"   ,"errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(1)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(%i,1)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(%t,1)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(3,[])","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(-2,%nan)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(-2,%eps)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(-3,6)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(-3,0)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(-%inf,-2)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(-2,-2)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+assert_checkfalse(execstr("nthroot(-2,2)","errcatch") == 0);
+lasterror(execstr("10000","errcatch") == 0)
+
+
+// 2. Singular Values
+// ==================
+assert_checkalmostequal(nthroot(2,-2),0.7071068, 1.e-5);
+assert_checkalmostequal(nthroot(2,2),1.4142136, 1.e-5);
+assert_checkalmostequal(nthroot(%eps,3),0.0000061, 1.e-2);
+assert_checkalmostequal(nthroot([1 2],2),[1 1.4142136], 1.e-5);
+assert_checkequal(nthroot(-2,%inf),-1);
+assert_checkequal(nthroot(3,%inf),1);
+assert_checkequal(nthroot(3,-%inf),1);
+assert_checkequal(nthroot(-3,%inf),-1);
+assert_checkequal(nthroot(3,%nan),%nan);
+assert_checkequal(nthroot(3,-%nan),%nan);
+assert_checkequal(nthroot(3,%eps),%inf);
+assert_checkequal(nthroot(3,-%eps),0);
+assert_checkequal(nthroot(3,0),%inf);
+assert_checkequal(nthroot(1,0),%nan);
+
+assert_checkequal(nthroot([1 2],%inf),[1 1]);
+assert_checkequal(nthroot([1 2],%nan),[%nan %nan]);
+assert_checkequal(nthroot([1 2],%eps),[1 %inf]);
+assert_checkequal(nthroot([1 2],0),[%nan %inf]);
+
+assert_checkequal(nthroot(0,0),0);
+assert_checkequal(nthroot(0,7),0);
+assert_checkequal(nthroot(0,-7),%inf);
+assert_checkequal(nthroot(0,%inf),1);
+assert_checkequal(nthroot(0,-%inf),1);
+assert_checkequal(nthroot(0,%nan),%nan);
+assert_checkequal(nthroot(0,%eps),0);
+assert_checkequal(nthroot(0,-%eps),%inf);
+
+assert_checkequal(nthroot([0;-1],%inf),[1;-1]);
+assert_checkequal(nthroot([0;1],0),[0;%nan]);
+
+// 3. Empty Matrix
+//==================
+assert_checkequal(nthroot([],-2),[]);
+assert_checkequal(nthroot([],3),[]);
+assert_checkequal(nthroot([],%nan),[]);
+assert_checkequal(nthroot([],%inf),[]);
+assert_checkequal(nthroot([],-%inf),[]);
+assert_checkequal(nthroot([],%eps),[]);
+assert_checkequal(nthroot([],-%eps),[]);
+assert_checkequal(nthroot([],0),[]);
+
+// 4. Limit Values
+// ================
+assert_checkequal(nthroot(-%inf,-7),0);
+assert_checkequal(nthroot(-%inf,7),-%inf);
+assert_checkequal(nthroot(%inf,-7),0);
+assert_checkequal(nthroot(%inf,7),%inf);
+assert_checkequal(nthroot(%inf,%inf),1);
+assert_checkequal(nthroot(%inf,-%inf),1);
+assert_checkequal(nthroot(-%inf,%inf),-1);
+assert_checkequal(nthroot(-%inf,-%inf),-1);
+assert_checkequal(nthroot(%inf,%inf),1);
+assert_checkequal(nthroot(%inf,%nan),%nan);
+assert_checkequal(nthroot(%inf,%eps),%inf);
+assert_checkequal(nthroot(%inf,-%eps),0);
+assert_checkequal(nthroot(%inf,0),%inf);
+
+assert_checkequal(nthroot([%inf;%nan],3),[%inf;%nan]);
+assert_checkequal(nthroot([%inf;%nan],%nan),[%nan;%nan]);
+assert_checkequal(nthroot([%inf;%nan],0),[%inf;%nan]);
+
+assert_checkequal(nthroot([%inf;%eps],%eps),[%inf;0]);
+assert_checkequal(nthroot([%inf;%eps],%nan),[%nan;%nan]);
+assert_checkequal(nthroot([%inf;1],0),[%inf;%nan]);
+
+// 5. Not A Number
+// =================
+assert_checkequal(nthroot(%nan,-2),%nan);
+assert_checkequal(nthroot(%nan,%inf),%nan);
+assert_checkequal(nthroot(%nan,-%inf),%nan);
+assert_checkequal(nthroot(%nan,-%eps),%nan);
+assert_checkequal(nthroot(%nan,0),%nan);
+
+// 6. X = %eps
+// ===========
+assert_checkequal(nthroot(%eps,%inf),1);
+assert_checkequal(nthroot(%eps,-%inf),1);
+assert_checkequal(nthroot(-%eps,%inf),-1);
+assert_checkequal(nthroot(-%eps,-%inf),-1);
+assert_checkequal(nthroot(%eps,%inf),1);
+assert_checkequal(nthroot(%eps,%nan),%nan);
+assert_checkequal(nthroot(%eps,%eps),0);
+assert_checkequal(nthroot(%eps,-%eps),%inf);
+assert_checkequal(nthroot(%eps,0),0);