diff options
author | Shashank | 2017-05-29 12:40:26 +0530 |
---|---|---|
committer | Shashank | 2017-05-29 12:40:26 +0530 |
commit | 0345245e860375a32c9a437c4a9d9cae807134e9 (patch) | |
tree | ad51ecbfa7bcd3cc5f09834f1bb8c08feaa526a4 /modules/development_tools/help | |
download | scilab_for_xcos_on_cloud-0345245e860375a32c9a437c4a9d9cae807134e9.tar.gz scilab_for_xcos_on_cloud-0345245e860375a32c9a437c4a9d9cae807134e9.tar.bz2 scilab_for_xcos_on_cloud-0345245e860375a32c9a437c4a9d9cae807134e9.zip |
CMSCOPE changed
Diffstat (limited to 'modules/development_tools/help')
42 files changed, 5753 insertions, 0 deletions
diff --git a/modules/development_tools/help/en_US/addchapter.sce b/modules/development_tools/help/en_US/addchapter.sce new file mode 100755 index 000000000..64c03e3b8 --- /dev/null +++ b/modules/development_tools/help/en_US/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// 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.1-en.txt + +add_help_chapter("Development tools",SCI+"/modules/development_tools/help/en_US",%T); + diff --git a/modules/development_tools/help/en_US/assert/CHAPTER b/modules/development_tools/help/en_US/assert/CHAPTER new file mode 100755 index 000000000..f4b4d4cdd --- /dev/null +++ b/modules/development_tools/help/en_US/assert/CHAPTER @@ -0,0 +1 @@ +title = Assert
\ No newline at end of file diff --git a/modules/development_tools/help/en_US/assert/assert_0overview.xml b/modules/development_tools/help/en_US/assert/assert_0overview.xml new file mode 100755 index 000000000..422e10205 --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_0overview.xml @@ -0,0 +1,132 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + * Copyright (C) 2010-2011 - DIGITEO - Michael Baudin +--> +<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="fr" scilab:needs-examples="no" xml:id="assert_overview"> + <refnamediv> + <refname>Assert Overview</refname> + <refpurpose>An overview of the Assert module.</refpurpose> + </refnamediv> + <refsection> + <title>Purpose</title> + <para> + The goal of this module is to provide functions to check the + behavior of some other functions, for example in unit tests. + We emphasize the use of consistent tools for testing numerical issues, + with the goal of testing numerical algorithms more easily. + In particular, we provide a comparison function for two floating + point numbers, which allows to check that two numbers are "numerically almost equal", + i.e. that the relative error is small. + </para> + </refsection> + <refsection> + <title>Quick start</title> + <para> + The <literal>assert_checktrue</literal> function allows to + check that a matrix of booleans is true. + The following assertion fails and generate an error. + </para> + <programlisting role="example"><![CDATA[ +assert_checktrue ( [%t %F] ); + ]]></programlisting> + <para> + The <literal>assert_checkequal</literal> function allows to + check that two variables are equal. + The following assertion is a success and runs silently. + </para> + <programlisting role="example"><![CDATA[ +assert_checkequal ( %nan , %nan ); + ]]></programlisting> + <para> + The <literal>assert_checkalmostequal</literal> function allows to + check that a computed result is close to an expected result. + In the following script, we check that <literal>computed=1.23456</literal> + is close to <literal>expected=1.23457</literal>, but that + 11 digits have been lost with respect to the maximum + achievable accuracy. + </para> + <programlisting role="example"><![CDATA[ +assert_checkalmostequal ( 1.23456 , 1.23457 , 1.e11*%eps ); + ]]></programlisting> + <para> + A particular feature of the module is that all the assert functions + have the same output arguments. + This feature allows to get a uniform behavior and supports a + simple management of the errors in the case where an assertion is + not satisfied. + For example, consider the function <literal>assert_checktrue</literal>, + which calling sequence is: + </para> + <programlisting role="no-scilab-exec"><![CDATA[ +flag = assert_checktrue ( condition ) +flag = assert_checktrue ( condition ) +[flag,errmsg] = assert_checktrue ( condition ) + ]]></programlisting> + <para> + If any entry in condition is false, + <itemizedlist> + <listitem><para> + if the errmsg output variable is not used, an error is generated, + </para> + </listitem> + <listitem><para> + if the errmsg output variable is used, no error is generated. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The reason of this behavior is to be able to use assertions + both in scripts (e.g. unit tests) and in functions. + For example, in a typical unit test, the statement: + </para> + <programlisting role="example"><![CDATA[ +assert_checktrue ( 1+1==12 ); + ]]></programlisting> + <para> + will generate an error, as expected. + On the other hand, consider the situation where we want to insert + assertions checkings in a function. + We might want to manage the case where the assertion fails. + In this case, the calling sequence <literal>assert_checktrue ( condition )</literal> + generates an error, which interrupts the execution. + We may want to avoid this, by catching the error generated by + <literal>assert_checktrue</literal>. + This requires to use the <literal>execstr</literal> function and + may lead to the following source code. + </para> + <programlisting role="example"><![CDATA[ +function y = myfunction ( x ) + ierr=execstr("assert_checktrue ( x==12 )","errcatch"); + if ( ierr <> 0 ) then + error("Oups!") + end + y=x +endfunction + ]]></programlisting> + <para> + In this case, we suggest to use instead the calling + sequence <literal>[flag,errmsg] = assert_checktrue ( condition )</literal>, + which simplifies the processing of the error. + </para> + <programlisting role="example"><![CDATA[ +function y = myfunction2 ( x ) + [flag,errmsg] = assert_checktrue ( x==12 ) + if ( ~flag ) then + error("Oups!") + end + y=x +endfunction + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_checkalmostequal.xml b/modules/development_tools/help/en_US/assert/assert_checkalmostequal.xml new file mode 100755 index 000000000..f5517b8f7 --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_checkalmostequal.xml @@ -0,0 +1,272 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkalmostequal" xml:lang="en"> + <refnamediv> + <refname>assert_checkalmostequal</refname> + <refpurpose>Check that computed and expected are numerically close.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + flag = assert_checkalmostequal ( computed , expected ) + flag = assert_checkalmostequal ( computed , expected , reltol ) + flag = assert_checkalmostequal ( computed , expected , reltol , abstol ) + flag = assert_checkalmostequal ( computed , expected , reltol , abstol , comptype ) + [flag,errmsg] = assert_checkalmostequal ( ... ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>computed:</term> + <listitem> + <para> a matrix of doubles, a sparse matrix of doubles, or an hypermatrix of doubles, the computed result</para> + </listitem> + </varlistentry> + <varlistentry> + <term>expected :</term> + <listitem> + <para> a matrix of doubles, a sparse matrix of doubles, or an hypermatrix of doubles, the expected result</para> + </listitem> + </varlistentry> + <varlistentry> + <term>reltol :</term> + <listitem> + <para> a 1-by-1 matrix of doubles, the relative tolerance (default reltol=sqrt(%eps)).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>abstol :</term> + <listitem> + <para> a 1-by-1 matrix of doubles, the absolute tolerance (default abstol=0).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>comptype :</term> + <listitem> + <para> a 1-by-1 matrix of strings, "matrix" or "element" (default comptype="element"). The comparison type.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para> a 1-by-1 matrix of boolean, %t if computed is close to expected, %f if not</para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> a 1-by-1 matrix of strings, the error message. If flag==%t, then errormsg=="". If flag==%f, then errmsg contains the error message.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Performs silently if the two matrices of doubles or complex doubles + computed and expected are close. + The variables computed and expected can be exchanged without changing the result. + </para> + <para> + Any optional input argument equal to the empty matrix is replaced by its default value. + </para> + <para> + We use the following algorithm. + We compare first the real parts. In case of equality, we compare the imaginary parts. + </para> + <para> + The condition used is mixed relative and absolute: + <programlisting> + ( |e-c| <= reltol * max(|e|,|c|) + abstol ) + </programlisting> + If comptype="matrix", the norm is used. + If comptype="element", the absolute value are used and the two matrices are + almost equal if all the conditions are true. + </para> + <para> + The default value comptype="matrix" option performs the comparison for the matrices as a whole, + the norm of the difference of the matrices is used. + The comptype="element" option performs the comparison elementwise, i.e. + all the elements of the matrices must be almost equal. + Choosing between these two comparison types must be done with care. + For example, if we are checking the elementwise output of an elementary function, + we should choose the "element" comparison type, since we must compare the + matrix elements one after the other. + </para> + <para> + If the IEEE values %inf, -%inf or %nan values are in the matrices, + then they are almost equal only if the IEEE values are + at the same indices in the matrices. + </para> + <para> + The default comparison is based on a relative error, ensuring that 8 digits are common. + This allows to assert the number of significant digits in the computed result. + </para> + <para> + This procedure only works when the computed and expected variables + are matrices of doubles. + It will generate an error in any other case. + </para> + <para> + If the comparison shows that computed is not almost equal to expected, + <itemizedlist> + <listitem> + <para>if the errmsg output variable is not used, an error is generated,</para> + </listitem> + <listitem> + <para>if the errmsg output variable is used, no error is generated.</para> + </listitem> + </itemizedlist> + </para> + <para> + In the process of comparing the values, we separate %nan, +%inf, -%inf and remaining values. + Comparing nan values between them is not possible. This is why we compare the + indices where %nan value occurs. + If we form differences of infinity values, we produce %nan values. + This is why we compare the indices where +%inf values occurs. + We do the same for -%inf values. + Then, the non-nan, non-infinity values are actually compared. + </para> + <para> + The default comptype="element" option performs the comparison elementwise, i.e. + all the elements of the matrices must be almost equal. + The comptype="matrix" option performs the comparison for the matrices as a whole, + the norm of the difference of the matrices is used. + </para> + <para> + In general, the relative tolerance should be + set to a multiple of the machine precision %eps. + The relative tolerance should also be chosen with the lowest + possible magnitude, that is, we should configure + the tolerance as accurately as possible. + During the process of configuring the relative tolerance, we + suggest to use the following values, in that order : + 0 (all digits correct), %eps, 10*%eps, 100*%eps, 1.e3*%eps, 1.e4*%eps, ..., + 1.e17*%eps (no digit correct). + See below for examples of this. + </para> + <para> + This function takes into account for complex numbers. + We first compare the real parts of the input arguments. + If this fails, we immediately return. + If this succeeds, we compare the imaginary parts of the input arguments. + </para> + <para> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +// Comparisons which are successful. +// Relative error : +assert_checkalmostequal ( 1 , 1 ); +assert_checkalmostequal ( 1 , 1 , %eps ); +assert_checkalmostequal ( ones(10,1) , ones(10,1) , %eps ); +// Absolute error : +assert_checkalmostequal ( 1.23456789123456789e-30 , 0 , 0 , 1.e-10 ); +assert_checkalmostequal ( [1 %nan], [1 %nan] , 0 , %eps ); + +// Comparisons which are failures. +// Error message produced : +assert_checkalmostequal ( 1 , 2 , %eps ); +// Error message produced : +flag = assert_checkalmostequal ( 1 , 2 , %eps ) +// No error message produced : +[flag,errmsg] = assert_checkalmostequal ( 1 , 2 , %eps ) +assert_checkalmostequal ( 1 , [2 3] , %eps ); +assert_checkalmostequal ( [%nan 1], [1 %nan] , %eps ); +assert_checkalmostequal ( 1 + 5 * %eps , 1 , %eps ); +assert_checkalmostequal ( 1.23456789123456789e-30 , 1.3e-30 , %eps ); + +// In the case where expected is nonzero, the +// tolerance for relative error should be a +// multiple of %eps. +// The following test is a success and shows +// that less than 11 digits are lost with respect +// to the maximum possible accuracy. +assert_checkalmostequal ( 1.23456 , 1.23457 , 1.e11*%eps ); + +// We cannot exchange the relative and absolute tolerances. +// The following test pass: we use an absolute tolerance +// because the expected value is zero. +assert_checkalmostequal ( 1.23456789e-30 , 0 , 0 , 1.e-10 ); +// The following test fail: we use a relative tolerance. +assert_checkalmostequal ( 0 , 1.23456789e-30 , 1.e-10 ); + +// We must configure the tolerance as tightly as possible. +// The following test fails, because the tolerance is too small +// with respect to the given numbers. +assert_checkalmostequal ( 1.23456 , 1.23457 , %eps ); +// In order to get the number of common digits: +assert_computedigits(1.23456 , 1.23457) +// which returns 5.09... +// We now make a judgment on the accuracy and conclude it is acceptable: +assert_checkalmostequal ( 1.23456 , 1.23457 , 1.e-5 ); + +// We give here a practical example of the use of assert_checkalmostequal. +// We solve an averagely ill-conditionned system of linear +// equations, based on the Hilbert matrix. +n = 6; +// The expected value is set by ourselves. +expected = ones(n,1); +A = testmatrix("hilb",n); +// We compute the condition number of the matrix : ~10^8 +ceil(log10(cond(A))) +// This means that the number of digits lost, +// predicted by theory, is 8. +// The right-hand side is computed given A and expected. +b = A * expected; +// In this case, a Gauss algorithm with partial +// pivoting is used. +computed = A\b; +// The following test fails: we have lost some digits. +assert_checkalmostequal(computed,expected,%eps) +// We compute the actual number of common digits: from 10 to 12 +assert_computedigits(computed, expected) +// We accept this computation. +// The following test pass. +assert_checkalmostequal(computed,expected,1.e5*%eps); + +// The following examples show the difference between comptype="element" and "matrix". +// The following test does not pass. +assert_checkalmostequal ( [1 1.e5] , [2 1.e5] , 1.e-3 ) +// The following test pass with the matrix-based comparison. +assert_checkalmostequal ( [1 1.e5] , [2 1.e5] , 1.e-3 , [] , "matrix" ) + +// The following test pass. +// It is non-trivial to take into account for IEEE values. +[flag,errmsg] = assert_checkalmostequal ( [1.2345 %inf -%inf %nan] , [1.2346 %inf -%inf %nan] , 1.e-4 ) + +// This function takes into account for complex numbers. +// The following test pass. +assert_checkalmostequal ( 1+%i , 1+(1+1.e-4)*%i , 1.e-3 , [], "element" ); +// The following test fails. +assert_checkalmostequal ( 1+%i , 1+(1+1.e-4)*%i , 1.e-5 , [], "element" ); + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_checkequal.xml b/modules/development_tools/help/en_US/assert/assert_checkequal.xml new file mode 100755 index 000000000..75f62651a --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_checkequal.xml @@ -0,0 +1,115 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkequal" xml:lang="en"> + <refnamediv> + <refname>assert_checkequal</refname> + <refpurpose>Check that computed and expected are equal.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + assert_checkequal ( computed , expected ) + flag = assert_checkequal ( computed , expected ) + [flag,errmsg] = assert_checkequal ( computed , expected ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>computed:</term> + <listitem> + <para> the computed result</para> + </listitem> + </varlistentry> + <varlistentry> + <term>expected :</term> + <listitem> + <para> the expected result</para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para> a 1-by-1 matrix of boolean, %t if computed is equal to expected, %f if not</para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> a 1-by-1 matrix of strings, the error message. If flag==%t, then errormsg=="". If flag==%f, then errmsg contains the error message.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Performs silently if computed and expected are equal. + </para> + <para> + If the type of both input arguments is 1 (i.e. a real matrix), + we check that non-nan values are equal. + </para> + <para> + We compare first the real parts. In case of equality, we compare the imaginary parts. + </para> + <para> + If the comparison shows that computed is equal to expected, + <itemizedlist> + <listitem> + <para>if the errmsg output variable is not used, an error is generated,</para> + </listitem> + <listitem> + <para>if the errmsg output variable is used, no error is generated.</para> + </listitem> + </itemizedlist> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +// Tests with success +assert_checkequal ( %T , %T ); +flag = assert_checkequal ( list() , list() ); +[flag , errmsg] = assert_checkequal ( [%T %F], [%T %F] ); +assert_checkequal ( %nan , %nan ); + +// Tests with failure +assert_checkequal ( %F , %T ); +flag = assert_checkequal ( %F , %T ); +// No error produced : +[flag , errmsg] = assert_checkequal ( %F , %T ) +assert_checkequal ( [1 2], [3 4] ) +assert_checkequal ( 1 , [2 3] ) +assert_checkequal ( 1 , "b" ) + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> + <refsection> + <title>Bibliography</title> + <para>"Automated Software Testing for Matlab", Steven Eddins, 2009</para> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_checkerror.xml b/modules/development_tools/help/en_US/assert/assert_checkerror.xml new file mode 100755 index 000000000..b94c2d58d --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_checkerror.xml @@ -0,0 +1,256 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkerror" xml:lang="en"> + <refnamediv> + <refname>assert_checkerror</refname> + <refpurpose>Check that an instruction produces the expected + error. + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + flag = assert_checkerror ( instr , expectedmsg ) + flag = assert_checkerror ( instr , expectedmsg , expectederrnb ) + flag = assert_checkerror ( instr , expectedmsg , expectederrnb , a1, ... ) + [flag,errmsg] = assert_checkerror ( ... ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>instr:</term> + <listitem> + <para>a 1-by-1 matrix of strings, an expression to evaluate</para> + </listitem> + </varlistentry> + <varlistentry> + <term>expectedmsg :</term> + <listitem> + <para>a string or a string vector, the error message to be + produced + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>expectederrnb :</term> + <listitem> + <para>a 1-by-1 matrix of doubles, integer values, the error number + (default expectederrnb=[]). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>a1 :</term> + <listitem> + <para>an extra localization argument, passed to the + <literal>msprintf</literal> function. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para>a 1-by-1 matrix of boolean, %t if the correct error message + was produced, %f if not + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para>a 1-by-1 matrix of strings, the error message. If flag==%t, + then errormsg=="". If flag==%f, then errmsg contains the error + message. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para>If the expression does not generate an error, then + <literal>assert_checkerror</literal> generates an error. Performs silently + if the evaluated expression generates the expected error message. + </para> + <para> + If the error message <literal>expectedmsg</literal> is provided and + is not the empty matrix <literal>[]</literal>, we check that the generated + error number matches the expected one. If the error number + <literal>expectederrnb</literal> is provided and is not the empty matrix + <literal>[]</literal>, we check that the generated error number matches + the expected one. If the error message <literal>expectedmsg</literal> and + the error number <literal>expectederrnb</literal> cannot be equal to the + empty matrix <literal>[]</literal> at the same time: at least one of them + must be provided. + </para> + <para>The string matching is strict string equality: no pattern or regular + expression can be used. + </para> + <para>If the error message is not expected or the error number is not + expected, + <itemizedlist> + <listitem> + <para>if the errmsg output variable is not used, an error is + generated, + </para> + </listitem> + <listitem> + <para>if the errmsg output variable is used, no error is + generated. + </para> + </listitem> + </itemizedlist> + </para> + <para>The goal of this function is to enable the tester to check the error + cases in a simplified framework. Checking the error messages of a function + has the following advantages: + <itemizedlist> + <listitem> + <para>it checks that the correct error is generated when + needed, + </para> + </listitem> + <listitem> + <para>it checks that the error message is correctly + formatted, + </para> + </listitem> + <listitem> + <para>it checks that the error message is correctly + localized. + </para> + </listitem> + </itemizedlist> + </para> + <para>The expected message can be a localized message. In this case, the + message is compared with the output of the <literal>gettext</literal> + function, and depends on the local language. The extra argument + <literal>a1</literal> can be used for this purpose, for example to format + the localized message. All the extra arguments <literal>a1</literal>, + <literal>a2</literal>, ... are automatically passed to the + <literal>msprintf</literal> function before being compared to the computed + error message. + </para> + </refsection> + <refsection> + <title>Examples</title> + <para>We give several examples of using the + <literal>assert_checkerror</literal> function. We first have to define a + function to be tested. + </para> + <para> + The following function <literal>f</literal> generates an error when + the number of input arguments in wrong or the type of <literal>x</literal> + is wrong. + </para> + <programlisting role="example"><![CDATA[ +function y = f(x) + [lhs, rhs] = argn() + if ( rhs <> 1 ) then + lstr = gettext("%s: Wrong number of input argument: %d expected.\n") + errmsg = msprintf ( lstr , "f" , 1 ) + error(errmsg) + end + if ( typeof(x) <> "constant" ) then + lstr = gettext("%s: Wrong type for argument #%d: Matrix expected.\n") + errmsg = msprintf ( lstr , "f" , 1 ) + error(errmsg,123456789) + end + y = x +endfunction + ]]></programlisting> + <para>Our task is to check the error messages produced by this function. + The two following tests pass: the error message is the expected one. We + let <literal>assert_checkerror</literal> manage the localization, by + providing only the localized message and the extra parameter + <literal>"f"</literal> (the name of the function) and <literal>1</literal> + (the index of the input argument). These two extra parameters are used by + <literal>assert_checkerror</literal> to format the message and to convert + the "%s" and "%d" formats into their actual values. + </para> + <programlisting role="example"><![CDATA[ +lcl1 = "%s: Wrong number of input argument: %d expected.\n"; +assert_checkerror ( "y = f()" , lcl1 , [] , "f" , 1); + +lcl2 = "%s: Wrong type for argument #%d: Matrix expected.\n"; +assert_checkerror ( "y = f(""a"")" , lcl2 , [] , "f" , 1); + ]]></programlisting> + <para>On the other hand, if we make the assumption that the current locale + language is english, we could as well use the following statement. But + this is not a recommended practice, since the test will fail if the + current locale is French, for example. + </para> + <programlisting role="example"><![CDATA[ +assert_checkerror ( "y = f()" , "f: Wrong number of input argument: 1 expected." ); + ]]></programlisting> + <para>In the following test, we also check the error number.</para> + <programlisting role="example"><![CDATA[ +lcl1="%s: Wrong number of input argument: %d expected.\n"; +assert_checkerror ( "y=f()" , lcl1 , 10000 , "f" , 1); + +lcl2 = "%s: Wrong type for argument #%d: Matrix expected.\n"; +assert_checkerror ( "y=f(""a"")" , lcl2 , 123456789 , "f" , 1); + ]]></programlisting> + <para>The two following tests fail.</para> + <programlisting role="example"><![CDATA[ +assert_checkerror ( "y = f()" , "oups" ); + +msg1 = msprintf(gettext("%s: Wrong number of input argument: %d expected.\n"), "f", 1); +assert_checkerror ( "y = f()" , msg1 , 12 ); + ]]></programlisting> + <para>When errmsg is given as output argument, no error is generated, as + in the following example. Notice the content of the + <literal>flag</literal> and <literal>errmsg</literal> variables. + </para> + <programlisting role="example"><![CDATA[ +// A test which pass: flag is %t, errmsg is empty +msg1 = msprintf(gettext("%s: Wrong number of input argument: %d expected.\n"), "f", 1); +[flag, errmsg] = assert_checkerror ( "y = f()" , msg1 ) + +// A test which fail: flag is %f, errmsg is not empty +[flag, errmsg] = assert_checkerror ( "y = f()" , "oups" ) + ]]></programlisting> + <para>The messages in the two following tests are localized, so that they + can work whatever the current language is. Instead of using the extra + parameter <literal>a1</literal>, we directly localize the message, which + is less short, but is a perfectly valid code. + </para> + <programlisting role="example"><![CDATA[ +msg1 = msprintf(gettext("%s: Wrong number of input argument: %d expected.\n"), "f", 1); +assert_checkerror ( "y = f()" , msg1 ); + +msg2 = msprintf(gettext("%s: Wrong type for argument #%d: Matrix expected.\n"), "f", 1); +assert_checkerror ( "y = f(""a"")" , msg2 ); + ]]></programlisting> + <para>It may happen that we want to just test the error number, but not + the error message. The following script just checks that the generated + error number is 123456789 when the first argument is not a matrix of + doubles: we do not check the error message. + </para> + <programlisting role="example"><![CDATA[ +assert_checkerror("f(""foo"")", [], 123456789); + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced</revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_checkfalse.xml b/modules/development_tools/help/en_US/assert/assert_checkfalse.xml new file mode 100755 index 000000000..663e8a28f --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_checkfalse.xml @@ -0,0 +1,105 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkfalse" xml:lang="en"> + <refnamediv> + <refname>assert_checkfalse</refname> + <refpurpose>Check that condition is false.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + flag = assert_checkfalse ( condition ) + flag = assert_checkfalse ( condition ) + [flag,errmsg] = assert_checkfalse ( condition ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>condition:</term> + <listitem> + <para> a matrix of booleans</para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para> a 1-by-1 matrix of boolean, %t if condition is false, %f if not</para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> a 1-by-1 matrix of strings, the error message. If flag==%t, then errormsg=="". If flag==%f, then errmsg contains the error message.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Performs silently if all entries in <literal>condition</literal> are false. + </para> + <para> + Generates an error if any entry in <literal>condition</literal> + is true. + Generates an error if <literal>condition</literal> is not a boolean. + </para> + <para> + If any entry in condition is true, + <itemizedlist> + <listitem> + <para>if the errmsg output variable is not used, an error is generated,</para> + </listitem> + <listitem> + <para>if the errmsg output variable is used, no error is generated.</para> + </listitem> + </itemizedlist> + </para> + <para> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +// Tests which pass +assert_checkfalse ( %f ); +flag = assert_checkfalse ( %f ) +[flag,errmsg] = assert_checkfalse ( %f ) +[flag,errmsg] = assert_checkfalse ( [%f %f] ); + +// Tests which fail +assert_checkfalse ( [%t %f] ); +flag = assert_checkfalse ( [%t %f] ) +// No error generated +[flag,errmsg] = assert_checkfalse ( [%t %f] ) + +// Wrong calls +assert_checkfalse ( "a" ) + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_checkfilesequal.xml b/modules/development_tools/help/en_US/assert/assert_checkfilesequal.xml new file mode 100755 index 000000000..cded671a8 --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_checkfilesequal.xml @@ -0,0 +1,210 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkfilesequal" xml:lang="en"> + <refnamediv> + <refname>assert_checkfilesequal</refname> + <refpurpose>Check that two files are equal.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + flag = assert_checkfilesequal ( filecomp , fileref ) + flag = assert_checkfilesequal ( filecomp , fileref , compfun ) + [flag,errmsg] = assert_checkfilesequal ( ... ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>filecomp :</term> + <listitem> + <para> a 1-by-1 matrix of strings, the computed file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>fileref :</term> + <listitem> + <para> a 1-by-1 matrix of strings, the reference file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>compfun :</term> + <listitem> + <para> a function or a list, the comparison function (default compfun = []). If no comparison function is used, the equality operator "==" is used. See below for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para> a 1-by-1 matrix of boolean, %t if computed is close to expected, %f if not</para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> a 1-by-1 matrix of strings, the error message. If flag==%t, then errormsg=="". If flag==%f, then errmsg contains the error message.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Performs silently if the files are equal. + Generates an error if filecomp or fileref do not exist. + Generates an error if the content of the files are not equal. + </para> + <para> + If the files are not equal, + <itemizedlist> + <listitem> + <para>if the errmsg output variable is not used, an error is generated,</para> + </listitem> + <listitem> + <para>if the errmsg output variable is used, no error is generated.</para> + </listitem> + </itemizedlist> + </para> + <para> + If the comparison function compfun is a function, it should have header areequal = compfun ( txtcomp , txtref ) + where txtcomp is the content of the computed file, txtref is the content of the reference file and areequal + is a boolean. The areequal boolean is true if the two contents are equal. + If compfun is a list, it should be list (cf,a1,a2,...), where cf is a comparison function, + and the arguments a1, a2, will be automatically be appended at the + end of the calling sequence of cf. + </para> + <para> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +// +// Prepare data for the tests +// fileref1 : three lines of text. +// filecomp1 : == fileref1 +// filecomp2 : <> fileref1 +fileref1 = fullfile(TMPDIR,"fileref.txt"); +txt1 = [ +"Line #1" +"Line #2" +"Line #3" +]; +fd = mopen(fileref1,"w"); +mputl(txt1,fd); +mclose(fd); +filecomp1 = fullfile(TMPDIR,"filecomp1.txt"); +fd = mopen(filecomp1,"w"); +mputl(txt1,fd); +mclose(fd); +filecomp2 = fullfile(TMPDIR,"filecomp2.txt"); +txt2 = [ +"Line #1" +"Line #4" +"Line #3" +]; +fd = mopen(filecomp2,"w"); +mputl(txt2,fd); +mclose(fd); + +// A test which pass +flag = assert_checkfilesequal ( filecomp1 , fileref1 ) +[flag,errmsg] = assert_checkfilesequal ( filecomp1 , fileref1 ) + +// Failure: filecomp2 <> fileref1 +// Error generated +flag = assert_checkfilesequal ( filecomp2 , fileref1 ) +// No error generated +[flag,errmsg] = assert_checkfilesequal ( filecomp2 , fileref1 ) + +// Prepare data for the tests +// fileref2 == filecomp3, given that comment lines are ignored. +// fileref2 <> filecomp4, given that comment lines are ignored. +// Notice that the comments are inserted at different positions in the files: +// sometimes at the beginning, sometimes in the middle. +fileref2 = fullfile(TMPDIR,"fileref2.txt"); +txt = [ +"// bla 2" +"Line #1" +"// bla 2" +"Line #2" +"Line #3" +]; +fd = mopen(fileref2,"w"); +mputl(txt,fd); +mclose(fd); +filecomp3 = fullfile(TMPDIR,"filecomp3.txt"); +txt = [ +"Line #1" +"// bla 5168" +"Line #2" +"Line #3" +"// bla oups" +]; +fd = mopen(filecomp3,"w"); +mputl(txt,fd); +mclose(fd); +filecomp4 = fullfile(TMPDIR,"filecomp4.txt"); +txt = [ +"// bla 3" +"Line #1" +"Line #4" +"// bla 5168" +"Line #3" +"// bla oups" +]; +fd = mopen(filecomp4,"w"); +mputl(txt,fd); +mclose(fd); + +// A test with a comparison function which ignores comment lines. +function otxt = myfilter ( itxt ) +nr = size(itxt,"r") +// This is the pattern for a comment line of the form "// blabla" +pattern = "/\/\/.*/" +k = 1 +for i = 1 : nr +start = regexp(itxt(i),pattern) +if ( start == [] ) then +otxt(k) = itxt(i) +k = k + 1 +end +end +endfunction +function areequal = mycompfun ( ctxt , etxt ) +ctxt = myfilter ( ctxt ) +etxt = myfilter ( etxt ) +areequal = ( ctxt == etxt ) +endfunction +// +// A test which pass +[flag,errmsg] = assert_checkfilesequal ( filecomp3 , fileref2 , mycompfun ) +// A test which fails +[flag,errmsg] = assert_checkfilesequal ( filecomp4 , fileref2 , mycompfun ) + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_checktrue.xml b/modules/development_tools/help/en_US/assert/assert_checktrue.xml new file mode 100755 index 000000000..0d58ba9c2 --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_checktrue.xml @@ -0,0 +1,105 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checktrue" xml:lang="en"> + <refnamediv> + <refname>assert_checktrue</refname> + <refpurpose>Check that condition is true.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + flag = assert_checktrue ( condition ) + flag = assert_checktrue ( condition ) + [flag,errmsg] = assert_checktrue ( condition ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>condition:</term> + <listitem> + <para> a matrix of booleans</para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para> a 1-by-1 matrix of boolean, %t if condition is true, %f if not</para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> a 1-by-1 matrix of strings, the error message. If flag==%t, then errormsg=="". If flag==%f, then errmsg contains the error message.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Performs silently if all entries in <literal>condition</literal> are true. + </para> + <para> + Generates an error if any entry in the <literal>condition</literal> matrix + is false. + Generates an error if <literal>condition</literal> is not a boolean. + </para> + <para> + If any entry in condition is false, + <itemizedlist> + <listitem> + <para>if the errmsg output variable is not used, an error is generated,</para> + </listitem> + <listitem> + <para>if the errmsg output variable is used, no error is generated.</para> + </listitem> + </itemizedlist> + </para> + <para> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +// Tests which pass +assert_checktrue ( %t ); +flag = assert_checktrue ( %t ) +[flag,errmsg] = assert_checktrue ( %t ) +[flag,errmsg] = assert_checktrue ( [%t %t] ); + +// Tests which fail +assert_checktrue ( [%t %f] ); +flag = assert_checktrue ( [%t %f] ) +// No error generated +[flag,errmsg] = assert_checktrue ( [%t %f] ) + +// Wrong calls +assert_checktrue ( "a" ) + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_comparecomplex.xml b/modules/development_tools/help/en_US/assert/assert_comparecomplex.xml new file mode 100755 index 000000000..8b57afeb7 --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_comparecomplex.xml @@ -0,0 +1,179 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_comparecomplex" xml:lang="en"> + <refnamediv> + <refname>assert_comparecomplex</refname> + <refpurpose>Compare complex numbers with a tolerance.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + order = assert_comparecomplex ( a , b ) + order = assert_comparecomplex ( a , b , reltol ) + order = assert_comparecomplex ( a , b , reltol , abstol ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>a :</term> + <listitem> + <para> a 1-by-1 matrix of doubles, the first value to be compared</para> + </listitem> + </varlistentry> + <varlistentry> + <term>b :</term> + <listitem> + <para> a 1-by-1 matrix of doubles, the second value to be compared</para> + </listitem> + </varlistentry> + <varlistentry> + <term>reltol :</term> + <listitem> + <para> a 1-by-1 matrix of doubles, the relative tolerance (default reltol=sqrt(%eps)).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>abstol :</term> + <listitem> + <para> a 1-by-1 matrix of doubles, the absolute tolerance (default abstol=0).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>order :</term> + <listitem> + <para> a 1-by-1 matrix of doubles, integer values, the order. Returns order=0 is a is almost equal to b, order=-1 if a < b, order=+1 if a > b.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Compare first by real parts, then by imaginary parts. + Takes into account numerical accuracy issues, by using + a mixed relative and absolute tolerance criteria. + </para> + <para> + Any optional input argument equal to the empty matrix is replaced by its default value. + </para> + <para> + We use the following algorithm. + </para> + <para> + We compare first the real parts. In case of tie, we compare the imaginary parts. + </para> + <para> + We process the IEEE values and choose the order : -%inf < 0 < %inf < %nan. + If none of the values is special, we use the condition : + <programlisting> + cond = ( abs(a-b) <= reltol * max(abs(a),abs(b)) + abstol ) + </programlisting> + </para> + <para> + This algorithm is designed to be used into sorting + algorithms. + It allows to take into account for the portability issues + related to the outputs of functions producing + matrix of complex doubles. + If this algorithm is plugged into a sorting function, + it allows to consistently produce a sorted matrix, + where the order can be independent of the operating system, + the compiler or other forms of issues modifying the + order (but not the values). + </para> + <para> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +// Compare real values +assert_comparecomplex ( 1 , -1 ) // 1 +assert_comparecomplex ( -1 , 1 ) // -1 +assert_comparecomplex ( 1 , 1 ) // 0 + +// Compare complex values #1 +assert_comparecomplex ( 1+2*%i , 1+3*%i ) // -1 +assert_comparecomplex ( 1+3*%i , 1+2*%i ) // 1 +assert_comparecomplex ( 1+2*%i , 1+2*%i ) // 0 + +// Compare complex values #2 +assert_comparecomplex ( 1+%i , -1+%i ) // 1 +assert_comparecomplex ( -1+%i , 1+%i ) // -1 +assert_comparecomplex ( 1+%i , 1+%i ) // 0 +[order,msg] = assert_comparecomplex ( 1+%i , 1+%i ) + +// Compare with tolerances : equality cases +assert_comparecomplex ( 1.2345+%i , 1.2346+%i , %eps , 1.e-3 ) // 0 +assert_comparecomplex ( 1.2345+%i , 1.2346+%i , 1.e12*%eps , 0 ) // 0 +assert_comparecomplex ( 1+1.2345*%i , 1+1.2347*%i , %eps , 1.e-3 ) // 0 +assert_comparecomplex ( 1+1.2345*%i , 1+1.2347*%i , 1.e12*%eps , 0 ) // 0 + +// Compare more realistic data +x = [ +-0.123452 - 0.123454 * %i +-0.123451 + 0.123453 * %i +0.123458 - 0.123459 * %i +0.123456 + 0.123457 * %i +]; +// Consider less than 4 significant digits +for i = 1 : size(x,"*")-1 +order = assert_comparecomplex ( x(i) , x(i+1) , 1.e-4 ); +mprintf("compare(x(%d),x(%d))=%d\n",i,i+1,order) +end + +// Compare data from bug #415 +x = [ +-1.9914145 +-1.895889 +-1.6923826 +-1.4815461 +-1.1302576 +-0.5652256 - 0.0655080 * %i +-0.5652256 + 0.0655080 * %i +0.3354023 - 0.1602902 * %i +0.3354023 + 0.1602902 * %i +1.3468911 +1.5040136 +1.846668 +1.9736772 +1.9798866 +]; +// Consider less than 4 significant digits +for i = 1 : size(x,"*")-1 +order = assert_comparecomplex ( x(i) , x(i+1) , 1.e-5 ); +mprintf("compare(x(%d),x(%d))=%d\n",i,i+1,order) +end + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> + <refsection> + <title>Bibliography</title> + <para>http://gitweb.scilab.org/?p=scilab.git;a=blob;f=scilab/modules/polynomials/tests/nonreg_tests/bug_415.tst;h=0c716a3bed0dfb72c831972d19dbb0814dffde2b;hb=HEAD</para> + <para>http://gitweb.scilab.org/?p=scilab.git;a=blob_plain;f=scilab/modules/cacsd/tests/nonreg_tests/bug_68.tst;h=920d091d089b61bf961ea9e888b4d7d469942a14;hb=4ce3d4109dd752fce5f763be71ea639e09a12630</para> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_computedigits.xml b/modules/development_tools/help/en_US/assert/assert_computedigits.xml new file mode 100755 index 000000000..4b516a95e --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_computedigits.xml @@ -0,0 +1,150 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_computedigits" xml:lang="en"> + <refnamediv> + <refname>assert_computedigits</refname> + <refpurpose>Returns the number of significant digits in computed result.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + d = assert_computedigits ( computed , expected ) + d = assert_computedigits ( computed , expected , basis ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>computed :</term> + <listitem> + <para> a matrix of doubles, the computed value</para> + </listitem> + </varlistentry> + <varlistentry> + <term>expected :</term> + <listitem> + <para> a matrix of doubles, the expected value</para> + </listitem> + </varlistentry> + <varlistentry> + <term>basis :</term> + <listitem> + <para> a 1-by-1 matrix of doubles, integer values, the basis (default basis=10)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>d :</term> + <listitem> + <para> a matrix of doubles, the number of significant digits.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Computes the number of significant digits in a computed + result with respect to a nonzero expected result, using the formula: + </para> + <para> + <latex> + \begin{eqnarray} + d = - \frac{\log_{10} ( r )}{\log_{10}(basis)} + \end{eqnarray} + </latex> + </para> + <para> + where r is the relative error defined by + </para> + <para> + <latex> + \begin{eqnarray} + r = \frac{|computed - expected|}{|expected|} + \end{eqnarray} + </latex> + </para> + <para> + Any optional input argument equal to the empty matrix is replaced by its default value. + </para> + <para> + The number of significant digits is between dmin = 0 and dmax = -log10(2^(-53)) which + is approximately 15.95 ~ 16. + In base 2, the number of significant bits is 53. + </para> + <para> + If expected is equal to computed, then d is set to its maximum value, i.e. dmax. + If not, if expected is zero and computed is nonzero, then d is set to its minimum + value, i.e. dmin=0. + </para> + <para> + The values of computed and expected cannot be exchanged, since the relative + error is based on the expected value. + </para> + <para> + The computation separates the real part and the imaginary parts of the + values. + The returned number of digits is the minimum of the number of digits for the + real and imaginary parts. + </para> + <para> + TODO : use computedigits inside an assert_digits ( computed , expected , dmin ) function + </para> + <para> + TODO : add a comptype option to make the comparison "matrix" (current is "element") + </para> + <para> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +d = assert_computedigits ( 1 , 1 ) // d ~ 16 +d = assert_computedigits ( 1 , 1 , 2 ) // d = 53 +d = assert_computedigits ( 0 , 0 ) // d ~ 16 +d = assert_computedigits ( 1 , 0 ) // d = 0 +d = assert_computedigits ( 0 , 1 ) // d = 0 +d = assert_computedigits ( 3.1415926 , %pi ) // d ~ 8 +d = assert_computedigits ( 3.1415926 , %pi , 2 ) // d ~ 26 +d = assert_computedigits ( [0 0 1 1] , [0 1 0 1] ) // d ~ [16 0 0 16] +d = assert_computedigits(ones(3,2),ones(3,2)) // d ~ 16 * ones(3,2) +d = assert_computedigits(1.224646799D-16,8.462643383D-18) // d = 0 + +// Check IEEE values +// d ~ [16 0 0 0] +d = assert_computedigits([%nan %nan %nan %nan],[%nan %inf -%inf 0]) +// d ~ [0 16 0 0] +d = assert_computedigits([%inf %inf %inf %inf],[%nan %inf -%inf 0]) +// d = [0 0 16 0] +d = assert_computedigits([-%inf -%inf -%inf -%inf],[%nan %inf -%inf 0]) +// d = [0 0 0 16] +d = assert_computedigits([0 0 0 0],[%nan %inf -%inf 0]) + +// Check complex values +d = assert_computedigits ( 1.2345 + %i*6.7891 , 1.23456789 + %i*6.789123456 ) // d ~ 4 + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_cond2reltol.xml b/modules/development_tools/help/en_US/assert/assert_cond2reltol.xml new file mode 100755 index 000000000..437305535 --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_cond2reltol.xml @@ -0,0 +1,149 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_cond2reltol" xml:lang="en"> + <refnamediv> + <refname>assert_cond2reltol</refname> + <refpurpose>Suggests a relative error, computed from the condition number.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + rtol = assert_cond2reltol ( condition ) + rtol = assert_cond2reltol ( condition , offset ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>condition :</term> + <listitem> + <para> a matrix of doubles, the condition number. The condition number must be strictly positive.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>offset :</term> + <listitem> + <para> a matrix of doubles, a shift for the number of required decimal digits (default offset=0). For example, offset=1 increases the accuracy requirement (decreases the relative tolerance by a factor 10^-1), offset=-1 decreases the accuracy requirement (increases the relative tolerance by a factor 10^1).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>rtol :</term> + <listitem> + <para> a matrix of doubles, the relative tolerance. The relative tolerance is strictly positive, lower than 1.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Depending on the condition number, returns the corresponding relative tolerance. + </para> + <para> + Any optional parameter equal to the empty matrix [] is set to its default value. + </para> + <para> + We emphasize that this relative tolerance is only a suggestion. + Indeed, there may be correct reasons of using a lower or a higher relative tolerance. + </para> + <para> + <itemizedlist> + <listitem> + <para> + Consider the case where an excellent algorithm is able to make accurate computations, + even for an ill-conditionned problem. + In this case, we may require more accuracy (positive offset). + </para> + </listitem> + <listitem> + <para> + Consider the case where there is a trade-off between performance and accuracy, where performance wins. + In this case, we may require less accuracy (negative offset). + </para> + </listitem> + </itemizedlist> + </para> + <para> + Any scalar input argument is expanded to a matrix of doubles of the same size as the other input arguments. + </para> + <para> + We compute the number of required digits d, then the relative tolerance is 10^-d. + </para> + <para> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +assert_cond2reltol ( 0 ) // 1.110D-16 +assert_cond2reltol ( 1 ) // 1.110D-16 +assert_cond2reltol ( 1.e1 ) // 1.110D-15 +assert_cond2reltol ( 1.e2 ) // 1.110D-14 +assert_cond2reltol ( 1.e3 ) // 1.110D-13 +assert_cond2reltol ( 1.e16 ) // 1 +assert_cond2reltol ( 1.e17 ) // 1 +assert_cond2reltol ( 1.e18 ) // 1 + +// Matrix input. +condition = [0,1,10,100,1000,1.D13,1.D14,1.D15,1.D16,1.D17,1.D18]; +expected = [1.110D-16 1.110D-16 1.110D-15 1.110D-14 1.110D-13 0.0011102 0.0111022 0.1110223 1. 1. 1.]; +assert_cond2reltol ( condition ) + +// Using offset +// Negative offset : require less accuracy +assert_cond2reltol ( 1.e2 , [0 -1] ) // [1.1D-14 1.1D-13] +// Positive offset : requires more accuracy +// See that the impact of offset is constrained. +assert_cond2reltol ( 1.e2 , [0 1 2 3] ) // [1.1D-14 1.1D-15 1.1D-16 1.1D-16] +// Negative offset +// See that the impact of offset is constrained. +assert_cond2reltol ( 1.e14 , [0 -1 -2 -3] ) // [1.1D-02 1.1D-01 1 1] + +// Plot the relative tolerance depending on the condition +condition = logspace(0,18,1000); +r = assert_cond2reltol ( condition ); +plot(condition,r) +h=gcf(); +h.children.log_flags="lln"; +h.children.children.children.thickness=4; +xt = h.children.x_ticks; +xt.locations = 10^(0:2:18)'; +xt.labels = ["10^0";"10^2";"10^4";"10^6";"10^8";"10^10";"10^12";"10^14";"10^16";"10^18"]; +h.children.x_ticks=xt; +yt = h.children.y_ticks; +yt.locations = 10^-(0:2:18)'; +yt.labels = ["10^0";"10^-2";"10^-4";"10^-6";"10^-8";"10^-10";"10^-12";"10^-14";"10^-16";"10^-18"]; +h.children.y_ticks=yt; +xtitle("Relative tolerance","Condition","Relative tolerance"); +r = assert_cond2reltol ( condition , +3 ); +plot(condition,r,"r") +r = assert_cond2reltol ( condition , -3 ); +plot(condition,r,"g") +legend(["Offset=0","Offset=+3","Offset=-3"]); + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_cond2reqdigits.xml b/modules/development_tools/help/en_US/assert/assert_cond2reqdigits.xml new file mode 100755 index 000000000..681b1a9f9 --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_cond2reqdigits.xml @@ -0,0 +1,177 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_cond2reqdigits" xml:lang="en"> + <refnamediv> + <refname>assert_cond2reqdigits</refname> + <refpurpose>Suggests the number of required digits, given the condition number.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + d = assert_cond2reqdigits ( condition ) + d = assert_cond2reqdigits ( condition , offset ) + d = assert_cond2reqdigits ( condition , offset , b ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>condition :</term> + <listitem> + <para> a matrix of doubles, the condition number. The condition number must be strictly positive.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>offset :</term> + <listitem> + <para> a matrix of doubles, a shift for the number of required base-b digits (default offset=0). For example, offset=-1 produces a smaller number of required digits (reduces the required accuracy), offset=1 produces a larger number of required digits (increases the required accuracy).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>b :</term> + <listitem> + <para> a matrix of doubles, integer values, the b (default b = 10).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>d :</term> + <listitem> + <para> a matrix of doubles, the number of required digits. This is a positive real, between 0 and 15.95, if b=10 or between 0 and 53, if b=2.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Depending on the condition number, returns the corresponding number of required decimal digits. + </para> + <para> + Any optional parameter equal to the empty matrix [] is set to its default value. + </para> + <para> + We emphasize that this number of required digits is only a suggestion. + Indeed, there may be correct reasons of using a lower or a higher relative tolerance. + </para> + <para> + <itemizedlist> + <listitem> + Consider the case where an excellent algorithm is able to make accurate computations, + even for an ill-conditionned problem. + In this case, we may require more accuracy (positive offset). + </listitem> + <listitem> + Consider the case where there is a trade-off between performance and accuracy, where performance wins. + In this case, we may require less accuracy (negative offset). + </listitem> + </itemizedlist> + </para> + <para> + Any scalar input argument is expanded to a matrix of doubles of the same size as the other input arguments. + </para> + <para> + The algorithm is the following. + We compute the base-10 logarithm of condition, then subtract the offset. + This number represents the expected number of lost digits. + We project it into the interval [0,dmax], where dmax -log10(2^(-53)) is the maximum + achievable number of accurate digits for doubles. + We compute the number of required digits d, by difference between dmax and the number + of lost digits. + Then the relative tolerance is 10^-d. + </para> + <para> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +assert_cond2reqdigits ( 0 ) // 15.95459 +assert_cond2reqdigits ( 1 ) // 15.95459 +assert_cond2reqdigits ( 1.e1 ) // 14.95459 +assert_cond2reqdigits ( 1.e2 ) // 13.95459 +assert_cond2reqdigits ( 1.e3 ) // 12.95459 +assert_cond2reqdigits ( 1.e16 ) // 0 +assert_cond2reqdigits ( 1.e17 ) // 0 +assert_cond2reqdigits ( 1.e18 ) // 0 + +// Matrix input. +condition = [0,1,10,100,1000,1.D13,1.D14,1.D15,1.D16,1.D17,1.D18]; +assert_cond2reqdigits ( condition ) + +// Using offset +// Netative offset : decrease number of required digits (requires less accuracy) +assert_cond2reqdigits ( 1.e2 , [0 -1] ) // [13.95459 12.95459] +// Positive offset : increase number of required digits (requires more accuracy) +// See that the impact of offset is constrained. +assert_cond2reqdigits ( 1.e2 , [0 1 2 3] ) // [13.95459 14.95459 15.95459 15.95459] +// Netative offset (requires less accuracy) +// See that the impact of offset is constrained. +assert_cond2reqdigits ( 1.e14 , [0 -1 -2 -3] ) // [1.9545898 0.9545898 0. 0.] + +// Using base-2 +assert_cond2reqdigits ( 0 , [] , 2 ) // 53 +assert_cond2reqdigits ( 1 , [] , 2 ) // 53 +assert_cond2reqdigits ( 1.e1 , [] , 2 ) // 49.678072 +assert_cond2reqdigits ( 1.e2 , [] , 2 ) // 46.356144 +assert_cond2reqdigits ( 1.e3 , [] , 2 ) // 43.034216 +assert_cond2reqdigits ( 1.e16 , [] , 2 ) // 0 +assert_cond2reqdigits ( 1.e17 , [] , 2 ) // 0 +assert_cond2reqdigits ( 1.e18 , [] , 2 ) // 0 + +// Plot the number of required decimal digits depending on the condition +condition = logspace(0,18,1000); +d = assert_cond2reqdigits ( condition ); +plot(condition,d) +h=gcf(); +h.children.log_flags="lnn"; +h.children.children.children.thickness=4; +xt = h.children.x_ticks; +xt.locations = 10^(0:2:18)'; +xt.labels = ["10^0";"10^2";"10^4";"10^6";"10^8";"10^10";"10^12";"10^14";"10^16";"10^18"]; +h.children.x_ticks=xt; +xtitle("Number of required digits","Condition","Required decimal digits"); + +// Plot the number of required binary digits depending on the condition +condition = logspace(0,18,1000); +d = assert_cond2reqdigits ( condition , [] , 2 ); +plot(condition,d) +h=gcf(); +h.children.log_flags="lnn"; +h.children.children.children.thickness=4; +xt = h.children.x_ticks; +xt.locations = 10^(0:2:18)'; +xt.labels = ["10^0";"10^2";"10^4";"10^6";"10^8";"10^10";"10^12";"10^14";"10^16";"10^18"]; +h.children.x_ticks=xt; +xtitle("Number of required digits","Condition","Required binary digits"); +d = assert_cond2reqdigits ( condition , +10 , 2 ); +plot(condition,d,"r") +d = assert_cond2reqdigits ( condition , -10 , 2 ); +plot(condition,d,"g") +legend(["Offset=0","Offset=+10","Offset=-10"]); + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/assert/assert_generror.xml b/modules/development_tools/help/en_US/assert/assert_generror.xml new file mode 100755 index 000000000..46ebb38b9 --- /dev/null +++ b/modules/development_tools/help/en_US/assert/assert_generror.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_generror" xml:lang="en"> + <refnamediv> + <refname>assert_generror</refname> + <refpurpose>Generates an error.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + assert_generror ( errormsg ) + assert_generror ( errormsg , errornb ) + + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Parameters</title> + <variablelist> + <varlistentry> + <term>expectedmsg :</term> + <listitem> + <para> a 1-by-1 matrix of strings, the error message to be produced</para> + </listitem> + </varlistentry> + <varlistentry> + <term>expectederrnb :</term> + <listitem> + <para> a 1-by-1 matrix of doubles, integer values, the error number (default expectederrnb=[]).</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Calls the error function, with the given arguments. + </para> + <para> + This function is called by the assert_check* function each time an error + produced by the wrong match between expected and computed outputs is generated. + In the case where an assert_check* function receives a wrong number of input arguments, + a wrong number of output arguments, a wrong type of input argument or a wrong content + of input arguments, the regular error function is called. + This function can be customized to modify the behaviour of the assert_check* functions. + </para> + <para> + </para> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +// Both these calls generate an error +assert_generror ( "oups" ); +assert_generror ( "oups" , 123456789 ); + +// The following call generates an error. +assert_checktrue ( [%t %f] ); +// +// Define our own error handler +function myerror ( varargin ) + [lhs,rhs]=argn() + errormsg = varargin(1) + if ( rhs == 1 ) then + mprintf( "myerror: %s\n", errormsg ) + else + errornb = varargin(2) + mprintf( "myerror: %s (%d)\n", errormsg , errornb ) + end +endfunction +// +// Configure the new error handler +back=funcprot(); +funcprot(0); +olderrorfunction = assert_generror; +assert_generror = myerror; +funcprot(back); +// +// Check that the new error handler is in place +assert_checktrue ( [%t %f] ); +// +// Put back the regular error handler in place +back=funcprot(); +funcprot(0); +assert_generror = olderrorfunction; +funcprot(back); + + ]]></programlisting> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>Function introduced + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/bench_run.xml b/modules/development_tools/help/en_US/bench_run.xml new file mode 100755 index 000000000..98135c686 --- /dev/null +++ b/modules/development_tools/help/en_US/bench_run.xml @@ -0,0 +1,157 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 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.1-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" xmlns:scilab="http://www.scilab.org" xml:id="bench_run" xml:lang="en"> + <refnamediv> + <refname>bench_run</refname> + <refpurpose>Launch benchmark tests</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + bench_run() + bench_run(module[,test_name[,options]]) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>module</term> + <listitem> + <para>a vector of string. It can be the name of a module or the absolute path of a toolbox.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>test_name</term> + <listitem> + <para>a vector of string</para> + </listitem> + </varlistentry> + <varlistentry> + <term>options</term> + <listitem> + <para>a vector of string</para> + <itemizedlist> + <listitem> + <para>list : list of the benchmark tests available in a module</para> + </listitem> + <listitem> + <para>help : displays some examples of use in the Scilab console</para> + </listitem> + <listitem> + <para>nb_run=value : repeat the benchmark test value times</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Search for .tst files in benchmark test library + execute them, and display a report about execution time. + The .tst files are searched in directories SCI+"/modules/*/tests/benchmark". + </para> + <para> + Special tags may be inserted in the .tst file, which help to + control the processing of the corresponding test. These tags + are expected to be found in Scilab comments. + </para> + <para>These are the available tags :</para> + <itemizedlist> + <listitem> + <para> + <-- BENCH NB RUN : 10 --> + This test will be repeated 10 times. + </para> + </listitem> + <listitem> + <para> + <-- BENCH START --> + <-- BENCH END --> + The interesting part of the benchmark must be enclosed by these + tags. + </para> + </listitem> + </itemizedlist> + </refsection> + <refsection> + <title>Examples</title> + <para>Some simple examples of invocation of bench_run</para> + <programlisting role="example"><![CDATA[ +// Launch all tests +bench_run(); +bench_run([]); +bench_run([],[]); + +// Test one or several module +bench_run('core'); +bench_run('core',[]); +bench_run(['core','string']); + +// Launch one or several test in a specified module +bench_run('core',['trycatch','opcode']); + +// With options +bench_run([],[],'list'); +bench_run([],[],'help'); +bench_run([],[],'nb_run=2000'); + ]]></programlisting> + <para>An example of a benchmark file. This file corresponds to the + file + SCI/modules/linear_algebra/tests/benchmarks/bench_chol.tst. + </para> + <programlisting role="example"><![CDATA[ +// ============================================================================= +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2007-2008 - INRIA +// +// This file is distributed under the same license as the Scilab package. +// ============================================================================= + +//============================================================================== +// Benchmark for chol function +//============================================================================== + +// <-- BENCH NB RUN : 10 --> + +stacksize(30000000); + +a = 0; +b = 0; +a = rand(900, 900, 'n'); +a = a'*a; + +// <-- BENCH START --> +b = chol(a); +// <-- BENCH END --> + ]]></programlisting> + <para>The result of the test</para> + <programlisting role="example"><![CDATA[ +-->bench_run('linear_algebra','bench_chol') + + For Loop (as reference) ........................... 143.00 ms [ 1000000 x] + + 001/001 - [linear_algebra] bench_chol ...................... 130.60 ms [ 10 x] + ]]></programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="test_run">test_run</link> + </member> + </simplelist> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/example_run.xml b/modules/development_tools/help/en_US/example_run.xml new file mode 100755 index 000000000..f322218e4 --- /dev/null +++ b/modules/development_tools/help/en_US/example_run.xml @@ -0,0 +1,103 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2012 - Scilab Enterprises - Vincent COUVERT + * + * 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.1-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" xmlns:scilab="http://www.scilab.org" xml:id="example_run" xml:lang="en"> + <refnamediv> + <refname>example_run</refname> + <refpurpose>Launch the examples found in help pages.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + example_run() + example_run(moduleNames) + example_run(moduleNames, functionNames) + example_run(moduleNames, functionNames, language) + example_run(moduleNames, functionNames, language, testrunOptions, testrunExportToFile) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>moduleNames</term> + <listitem> + <para> + a string or a string vector: the name(s) of the modules to test. Default value is the value returned by <link linkend="getmodules">getmodules()</link>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>functionNames</term> + <listitem> + <para>a string or a string vector: the name(s) of the functions to test. If not given, all help pages of the module(s) will be tested.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>language</term> + <listitem> + <para>a string: the language of the help pages to test. Default value is "en_US".</para> + </listitem> + </varlistentry> + <varlistentry> + <term>testrunOptions</term> + <listitem> + <para> + Used as third input argument for <link linkend="test_run">test_run</link>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>testrunExportToFile</term> + <listitem> + <para> + Used as forth input argument for <link linkend="test_run">test_run</link>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + This function extracts the examples given in help pages and run them using <link linkend="test_run">test_run</link>. + </para> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"><![CDATA[ +if ~isempty(ls("SCI/modules/xml/help/en_US/*.xml")) then // Help XML sources must be available for this example + example_run("xml") + example_run("core", "insertion") + example_run("core", ["insertion"; "extraction"]) + example_run("core", "insertion", "en_US") +end + ]]></programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="test_run">test_run</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark>Function example_run introduced.</revremark> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/test_run.xml b/modules/development_tools/help/en_US/test_run.xml new file mode 100755 index 000000000..85520c62c --- /dev/null +++ b/modules/development_tools/help/en_US/test_run.xml @@ -0,0 +1,492 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) INRIA + * Copyright (C) 2009-2011 - DIGITEO - Michael Baudin + * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier: added 32/64bits separation + * + * 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.1-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" xmlns:scilab="http://www.scilab.org" xml:id="test_run" xml:lang="en"> + <refnamediv> + <refname>test_run</refname> + <refpurpose>Launch tests</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + status = test_run() + status = test_run(module) + status = test_run(module, test_name) + status = test_run(module, test_name, options, exportToFile) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>module</term> + <listitem> + <para>A String array. This input argument must be</para> + <itemizedlist> + <listitem> + <para> + the name of an internal Scilab module ("core", "time", ...) or a sub-module (e.g. "optimization|neldermead"). + </para> + </listitem> + <listitem> + <para> + the name of an ATOMS module ("module_lycee", "nisp", ...). To be taken into account, the module must be loaded when test_run() is called. + </para> + </listitem> + <listitem> + <para> + the absolute directory path of a module. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>test_name</term> + <listitem> + <para>A string array</para> + </listitem> + </varlistentry> + <varlistentry> + <term>options</term> + <listitem> + <para>A string array</para> + <variablelist> + <varlistentry> + <term>no_check_ref</term> + <listitem> + <para>does not check if the .dia and .dia.ref are equal</para> + </listitem> + </varlistentry> + <varlistentry> + <term>no_check_error_output</term> + <listitem> + <para>The error output stream is not checked. This option can be used when Scilab complains about the localization being not available.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>create_ref</term> + <listitem> + <para>create the .dia.ref file and does not check if the .dia and .dia.ref are equal</para> + </listitem> + </varlistentry> + <varlistentry> + <term>show_error</term> + <listitem> + <para>If an error occurs, show the last 10 lines of the execution</para> + </listitem> + </varlistentry> + <varlistentry> + <term>show_diff</term> + <listitem> + <para> + If a difference is found, show the result of the command <literal>diff -u</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>list</term> + <listitem> + <para>Does not perform the tests but displays a list of available tests</para> + </listitem> + </varlistentry> + <varlistentry> + <term>help</term> + <listitem> + <para>display some examples about how to use this command</para> + </listitem> + </varlistentry> + <varlistentry> + <term>mode_nw</term> + <listitem> + <para>Add the "-nw" option to the launch</para> + </listitem> + </varlistentry> + <varlistentry> + <term>mode_nwni</term> + <listitem> + <para>Add the "-nwni" option to the launch</para> + </listitem> + </varlistentry> + <varlistentry> + <term>nonreg_tests</term> + <listitem> + <para>runs only the non-regression tests, skipping unit tests</para> + </listitem> + </varlistentry> + <varlistentry> + <term>unit_tests</term> + <listitem> + <para>Runs only the unit tests, skipping non-regression tests</para> + </listitem> + </varlistentry> + <varlistentry> + <term>skip_tests</term> + <listitem> + <para>Skip the tests</para> + </listitem> + </varlistentry> + <varlistentry> + <term>enable_lt</term> + <listitem> + <para>Enable long-time execution tests</para> + </listitem> + </varlistentry> + <varlistentry> + <term>short_summary</term> + <listitem> + <para>Does not display statistics nor execution time after execution (only number of executed, passed, failed and skipped tests will be displayed on a single line).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>exportToFile</term> + <listitem> + <para> + Export to a XML file the result of the test. This file follows the specification of the XUnit format. + Note that the usage of this option enables <literal>show_diff</literal> and <literal>show_error</literal>. + </para> + <para> + If the file pointed by <varname>exportToFile</varname> already exists, the new result will be added to the existing file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>status</term> + <listitem> + <para> + Boolean value + Returns %t if no error has been detected + Returns %f if any error has been detected + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + Search for .tst files in the unit test and non-regression test library + execute them, and display a report about success of failures. + The .tst files are searched in directories SCI+"/modules/*/tests/unit_tests" + and SCI+"/modules/*/tests/nonreg_tests". + Whenever a test is executed, a .dia file is generated which contains + the full list of commands executed along with message which appears in the + console. When the script is done, the .dia file is compared with + the .dia.ref file which is expected to be in the same directory + as the .tst file. If the two file are different, the test fails. + </para> + <para> + Special tags may be inserted in the .tst file, which help to + control the processing of the corresponding test. These tags + are expected to be found in Scilab comments. + </para> + <para>These are the available tags:</para> + <itemizedlist> + <listitem> + <para> + <-- INTERACTIVE TEST --> + This test will be skipped because it is interactive. + </para> + </listitem> + <listitem> + <para> + <-- LONG TIME EXECUTION --> + This test will be skipped because it needs long-time duration. To enable + the test, call test_run with the following option: "enable_lt" + </para> + </listitem> + <listitem> + <para> + <-- NOT FIXED --> + This test will be skipped because it is a known, but unfixed bug. + </para> + </listitem> + <listitem> + <para> + <-- TEST WITH GRAPHIC --> + This test will not be executed if the option "mode_nwni" is used. + </para> + </listitem> + <listitem> + <para> + <-- NO TRY CATCH --> + </para> + </listitem> + <listitem> + <para> + <-- NO CHECK ERROR OUTPUT --> + The error output file is not checked + </para> + </listitem> + <listitem> + <para> + <-- NO CHECK REF --> + The .dia and the .dia.ref files are not compared. + </para> + </listitem> + <listitem> + <para> + <-- ENGLISH IMPOSED --> + This test will be executed with the -l en_US option. + </para> + </listitem> + <listitem> + <para> + <-- FRENCH IMPOSED --> + This test will be executed with the -l fr_FR option. + </para> + </listitem> + <listitem> + <para> + <-- CLI SHELL MODE --> + (was: <-- JVM NOT MANDATORY -->) + This test will be executed with scilab-cli (nwni mode) by default. + </para> + </listitem> + <listitem> + <para> + <-- WINDOWS ONLY --> + If the operating system isn't Windows, the test is skipped. + </para> + </listitem> + <listitem> + <para> + <-- UNIX ONLY --> + If the operating system isn't an Unix OS, the test is skipped. + </para> + </listitem> + <listitem> + <para> + <-- LINUX ONLY --> + If the operating system isn't GNU/Linux, the test is skipped. + </para> + </listitem> + <listitem> + <para> + <-- MACOSX ONLY --> + If the operating system isn't Mac OS X, the test is skipped. + </para> + </listitem> + <listitem> + <para> + <-- XCOS TEST --> + This test will launch all the necessary Xcos libs. This test + will be launched in nw mode. + </para> + </listitem> + </itemizedlist> + <para> + Each test is executed in a separated process, created with the "host" command. + That enables the current command to continue, even if the test as + created an unstable environment. It also enables the tests to be + independent from one another. + </para> + </refsection> + <refsection> + <title>Platform-specific tests</title> + <para> + It may happen that the output of a test depends on the platform on which it is + executed. In this case, the <literal>.ref</literal> file cannot be correct for + all platforms and unit tests may fail for some platform. In this case, we can + create a default <literal>.ref</literal> and create additional <literal>.ref</literal> + file for each platform. + </para> + <para> + The various platform-specific <literal>.ref</literal> files must have one of the following extensions. + </para> + <itemizedlist> + <listitem> + <para> + <literal>.unix.dia.ref</literal> for Unix platform, + </para> + </listitem> + <listitem> + <para> + <literal>.linux.dia.ref</literal> for GNU/Linux platform, + </para> + </listitem> + <listitem> + <para> + <literal>.linux32.dia.ref</literal> for GNU/Linux platform with 32bits processors, + </para> + </listitem> + <listitem> + <para> + <literal>.win.dia.ref</literal> for Windows platform, + </para> + </listitem> + <listitem> + <para> + <literal>.win32.dia.ref</literal> for Windows platform with 32bits processors, + </para> + </listitem> + <listitem> + <para> + <literal>.macosx.dia.ref</literal> for Mac OS X platform. + </para> + </listitem> + </itemizedlist> + <para> + The algorithm is the following. + First, the <literal>.ref</literal> is considered. If this file does not exist, + the platform-specific <literal>.ref</literal> file is examined depending on the current platform. + </para> + <itemizedlist> + <listitem> + <para> + on Windows platforms: <literal>.win.dia.ref</literal>, <literal>.win32.dia.ref</literal> + </para> + </listitem> + <listitem> + <para> + on Max OS X platforms: <literal>.unix.dia.ref</literal>, <literal>.macosx.dia.ref</literal>, + </para> + </listitem> + <listitem> + <para> + on GNU/Linux platforms: <literal>.unix.dia.ref</literal>, <literal>.linux.dia.ref</literal>, <literal>.linux32.dia.ref</literal>. + </para> + </listitem> + </itemizedlist> + </refsection> + <refsection> + <title>Examples</title> + <programlisting role="example"><![CDATA[ +// Launch all tests +// ============================================= + +test_run(); +test_run([]); +test_run([],[]); + +// Test one or several module +// ============================================= + +// Test one module +test_run('time'); + +// Test several modules +test_run(['time','string']); + +// Test a submodule +test_run('optimization|neldermead'); + +// Refer to a module by its path +test_run(SCI+'/modules/core'); + +// Launch a specific test +// ============================================= + +// One specific test +test_run('time','datenum'); + +// Several tests +test_run('time',['datenum';'calendar']); + +// Skip some tests +// ============================================= + +test_run('time',['datenum';'calendar'],'skip_tests'); + +// Options +// ============================================= + +// does not check if the .dia and .dia.ref are equal +test_run('time','datenum','no_check_ref'); + +// Create the .dia.ref file and does not check if the .dia and .dia.ref are equal +test_run([],[],'create_ref'); + +// Does not perform the tests but displays a list of available tests +test_run([],[],'list'); + +// Display some examples about how to use this command +test_run([],[],'help'); + +// Runs only the non-regression tests, skipping unit tests +test_run([],[],'nonreg_test'); + +// Runs only the unit tests, skipping non-regression tests +test_run([],[],'unit_test'); + +// Do not check the error output (std err) +test_run('boolean','bug_2799','no_check_error_output'); + +// Combine several options +test_run([],[],['no_check_ref','mode_nw']); + ]]></programlisting> + + <programlisting role="example"><![CDATA[ +// Run unitary tests of an external module (with his path) +test_run('SCI/contrib/toolbox_skeleton') + ]]></programlisting> + + <programlisting role="example"><![CDATA[ +// Export to a XML Xunit file +test_run('boolean',[],[],TMPDIR+"/boolean_test_run.xml"); +test_run('time','datenum',[],TMPDIR+"/time_datenum_test_run.xml"); + ]]></programlisting> + </refsection> + <refsection> + <title>Internal Design</title> + <para> + The tests are performed in the temporary directory, not in the directory + which originaly contain the tests files. + The .tst file is copied into the temporary directory, the test is performed + and the .dia.ref is copied back into the original location. + </para> + <para> + The .tst script is not run as is. Instead, a header and a footer are + inserted at the beginning and at the end of the .tst at the time + the script is copied into the temporary directory. + The role of this modification is to redirect the output messages + into the .dia file, so that the user can have a log file once the test + is performed. + </para> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>test_run returns a status: + <itemizedlist><listitem> + Returns %t if no error has been detected + </listitem> + <listitem> + Returns %f if any error has been detected + </listitem> + </itemizedlist> + <para> + <literal>show_diff</literal> and <literal>show_error</literal> added as new options + </para> + <para> + <literal>CLI SHELL MODE</literal> tag is added. Replaces <literal>JVM NOT MANDATORY</literal> (still supported) + </para> + <para> + <literal>test_run</literal> can work on an external module. + </para> + <para> + Fourth argument added to export to a XML file + </para> + </revdescription> + <revnumber>5.5.0</revnumber> + <revdescription>32/64bits separation available</revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/en_US/user.xml b/modules/development_tools/help/en_US/user.xml new file mode 100755 index 000000000..4be328556 --- /dev/null +++ b/modules/development_tools/help/en_US/user.xml @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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="user"> + <refnamediv> + <refname>user</refname> + <refpurpose>interfacing a Fortran or C routine</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis>[s_1,s_2,...,s_lhs]=user(e_1,e_2,...,e_rhs)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + With this command it is possible to use an external program + as a Scilab command + where <literal>(s_1,s_2,...,s_lhs)</literal> are the output variables and + <literal>(e_1,e_2,...,e_rhs)</literal> are the input variables. To insert this command + in Scilab one has to write a few lines in the <literal>user</literal> fortran subroutine + of Scilab. See <link linkend="intersci">intersci</link> or the Scilab documentation for more information. + </para> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="fort">fort</link> + </member> + <member> + <link linkend="link">link</link> + </member> + <member> + <link linkend="intersci">intersci</link> + </member> + </simplelist> + </refsection> +</refentry> diff --git a/modules/development_tools/help/fr_FR/addchapter.sce b/modules/development_tools/help/fr_FR/addchapter.sce new file mode 100755 index 000000000..46ca2b6a7 --- /dev/null +++ b/modules/development_tools/help/fr_FR/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// 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.1-en.txt + +add_help_chapter("Outils de développement",SCI+"/modules/development_tools/help/fr_FR",%T); + diff --git a/modules/development_tools/help/fr_FR/user.xml b/modules/development_tools/help/fr_FR/user.xml new file mode 100755 index 000000000..a3c0a7403 --- /dev/null +++ b/modules/development_tools/help/fr_FR/user.xml @@ -0,0 +1,34 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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="fr" xml:id="user"> + <refnamediv> + <refname>user</refname> + <refpurpose>interfaçage d'une routine Fortran ou C </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Séquence d'appel</title> + <synopsis>[s_1,s_2,...,s_lhs]=user(e_1,e_2,...,e_rhs)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + Avec cette commande il est possible d'utiliser un programme externe + comme une commande Scilab où + <literal>(s_1,s_2,...,s_lhs)</literal> sont les variables de sortie et + <literal>(e_1,e_2,...,e_rhs)</literal> sont les variables d'entrée. Pour utiliser cette commande dans Scilab il faut écrire quelques lignes dans la subroutine Fortran <literal>user</literal> de Scilab. Voir <link linkend="intersci">intersci</link> ou la documentation de Scilab pour plus d'informations. + </para> + </refsection> + <refsection role="see also"> + <title>Voir aussi</title> + <simplelist type="inline"> + <member> + <link linkend="fort">fort</link> + </member> + <member> + <link linkend="link">link</link> + </member> + <member> + <link linkend="intersci">intersci</link> + </member> + </simplelist> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/addchapter.sce b/modules/development_tools/help/ja_JP/addchapter.sce new file mode 100755 index 000000000..6c89bcfe7 --- /dev/null +++ b/modules/development_tools/help/ja_JP/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// 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.1-en.txt + +add_help_chapter("Development tools",SCI+"/modules/development_tools/help/ja_JP",%T); + diff --git a/modules/development_tools/help/ja_JP/assert/CHAPTER b/modules/development_tools/help/ja_JP/assert/CHAPTER new file mode 100755 index 000000000..f4b4d4cdd --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/CHAPTER @@ -0,0 +1 @@ +title = Assert
\ No newline at end of file diff --git a/modules/development_tools/help/ja_JP/assert/assert_0overview.xml b/modules/development_tools/help/ja_JP/assert/assert_0overview.xml new file mode 100755 index 000000000..fa22e5716 --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_0overview.xml @@ -0,0 +1,130 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + * Copyright (C) 2010-2011 - DIGITEO - Michael Baudin +--> +<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="ja" xml:id="assert_overview"> + <refnamediv> + <refname>assertの概要</refname> + <refpurpose>assertモジュールの概要.</refpurpose> + </refnamediv> + <refsection> + <title>目的</title> + <para> + このモジュールの目的は,ユニットテストのように + 他の関数の動作を書くにする関数を提供することです. + 数値計算アルゴリズムをより簡単にテストできることを目標にした + 数値的な問題をテストする一貫性があるツールを使用することに + 重点を置いています. + 具体的には,2つの浮動小数点数を比較する関数を提供し, + ここではその2つの数値が"数値的にほぼ等しい"こと, + すなわち相対誤差が小さい,を確認することができます. + </para> + </refsection> + <refsection> + <title>入門</title> + <para> + <literal>assert_checktrue</literal>関数により, + 論理値の行列がtrueであることを確認できます. + 以下のアサーションは失敗し,エラーを発生します. + </para> + <programlisting role="example"><![CDATA[ +assert_checktrue ( [%t %F] ); + ]]></programlisting> + <para> + <literal>assert_checkequal</literal> 関数により, + 2つの変数が等しいことを確認できます. + 以下のアサーションは成功し,そのまま実行されます. + </para> + <programlisting role="example"><![CDATA[ +assert_checkequal ( %nan , %nan ); + ]]></programlisting> + <para> + <literal>assert_checkalmostequal</literal>関数により, + 計算結果が予測した結果に近いことを確認できます. + 以下のスクリプトでは,<literal>computed=1.23456</literal> + が <literal>expected=1.23457</literal>に近いが, + 最大限達成可能な精度に対して11桁が失われていることを確認します. + </para> + <programlisting role="example"><![CDATA[ +assert_checkalmostequal ( 1.23456 , 1.23457 , 1.e11*%eps ); + ]]></programlisting> + <para> + このモジュールの特徴的な機能は, + 全てのアサート関数が同じ出力引数を有することです. + この機能により,動作を統一でき,アサーションがうまくいかない場合の + エラーの管理がシンプルになります. + 例えば,呼び出し手順が以下となる関数<literal>assert_checktrue</literal> + を見てみましょう: + </para> + <programlisting role="example"><![CDATA[ +flag = assert_checktrue ( condition ) +flag = assert_checktrue ( condition ) +[flag,errmsg] = assert_checktrue ( condition ) + ]]></programlisting> + <para> + conditionのあるエントリがfalseの場合, + <itemizedlist> + <listitem><para> + errmsg出力変数が使用されない場合,エラーが生成されます, + </para> + </listitem> + <listitem><para> + errmsg出力変数が使用された場合,エラーは生成されません. + </para> + </listitem> + </itemizedlist> + </para> + <para> + この動作の理由はスクリプト内(例:ユニットテスト)および + 関数内の両方でアサーションを使用出来ることです. + 例えば,典型的なユニットテストにおける以下の命令: + </para> + <programlisting role="example"><![CDATA[ +assert_checktrue ( 1+1==12 ); + ]]></programlisting> + <para> + は予想通りにエラーを生成します. + 次に,関数内にアサーションによる確認を挿入する場合を考えてみましょう. + アサーションが失敗したケースを管理することを考えます. + この場合,呼び出し手順<literal>assert_checktrue ( condition )</literal> + はエラーを生成し,実行を中断します. + <literal>assert_checktrue</literal>で生成されたエラーをキャッチすることで, + これを回避したい場合もありえます. + これには<literal>execstr</literal>を使用することが必要で, + 以下のようなソースコードとなります. + </para> + <programlisting role="example"><![CDATA[ +function y = myfunction ( x ) + ierr=execstr("assert_checktrue ( x==12 )","errcatch"); + if ( ierr <> 0 ) then + error("Oups!") + end + y=x +endfunction + ]]></programlisting> + <para> + この場合,エラー処理が簡単になる呼び出し手順 + <literal>[flag,errmsg] = assert_checktrue ( condition )</literal>を + 代わりに使用すると良いでしょう. + </para> + <programlisting role="example"><![CDATA[ +function y = myfunction2 ( x ) + [flag,errmsg] = assert_checktrue ( x==12 ) + if ( ~flag ) then + error("Oups!") + end + y=x +endfunction + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_checkalmostequal.xml b/modules/development_tools/help/ja_JP/assert/assert_checkalmostequal.xml new file mode 100755 index 000000000..0f256a88d --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_checkalmostequal.xml @@ -0,0 +1,295 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkalmostequal" xml:lang="ja"> + <refnamediv> + <refname>assert_checkalmostequal</refname> + <refpurpose>計算値と予測値が数値的に近いことを調べる.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + flag = assert_checkalmostequal ( computed , expected ) + flag = assert_checkalmostequal ( computed , expected , reltol ) + flag = assert_checkalmostequal ( computed , expected , reltol , abstol ) + flag = assert_checkalmostequal ( computed , expected , reltol , abstol , comptype ) + [flag,errmsg] = assert_checkalmostequal ( ... ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>computed:</term> + <listitem> + <para> + doubleの行列, doubleの疎行列, または + doubleのハイパー行列, 計算結果 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>expected :</term> + <listitem> + <para> + doubleの行列, doubleの疎行列, または + doubleのハイパー行列, 予測する結果 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>reltol :</term> + <listitem> + <para> doubleの1行1列行列, 相対許容誤差 + (デフォルト: reltol=sqrt(%eps)). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>abstol :</term> + <listitem> + <para> + doubleの1行1列行列, 絶対許容誤差 + (デフォルト: abstol=0). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>comptype :</term> + <listitem> + <para> + 文字列の1行1列行列, "matrix" または "element" + (デフォルト: comptype="element"). + 比較の型. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para> + 論理値の1行1列行列, + computed が expected に近い場合に %t, + そうでない場合に %f + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> + 文字列の1行1列行列, エラーメッセージ. + flag==%t の場合は errmsg="", + flag==%f の場合 errmsg にはエラーメッセージが + 代入されます. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + doubleまたは複素数doubleの2つの行列, computed と expected が近い + 場合にそのまま実行されます. + 変数computedとexpectedを交換しても結果に影響しません. + </para> + <para> + オプションの入力引数に空の行列w指定するとデフォルト値で + 置換されます. + </para> + <para> + 以下のようなアルゴリズムを使用します. + まず実部を比較します.実部が等しい場合,虚部を比較します. + </para> + <para> + 使用される条件は相対および絶対許容誤差を組み合わせたものです: + <programlisting> + ( |e-c| <= reltol * max(|e|,|c|) + abstol ) + </programlisting> + comptype="matrix" の場合, ノルムが使用されます. + comptype="element" の場合, + 絶対値が使用され, 全ての条件が true の場合に2つの行列が + ほぼ等しいとみなされます. + </para> + <para> + デフォルトの comptype="matrix" オプションでは + 行列全体についての比較が行われ, + 行列の差のノルムが使用されます. + comptype="element"オプションは要素毎の比較, + すなわち,行列の全ての要素がほぼ等しいこと,を行います. + これら2つの比較方法の選択は注意して行う必要があります. + 例えば,基本関数の出力を要素毎に確認する際には, + 行列の要素を順番に比較する必要があるため, + "element" 比較型を選ぶ必要があります. + </para> + <para> + IEEE値 %inf, -%inf または %nan が行列の中に存在する場合, + そのIEEE値が行列の同じ添字にある場合にのみほぼ等しいと + みなされます. + </para> + <para> + デフォルトの比較は相対誤差にもとづいており, + 8桁が共通であることを保障します. + これにより,計算結果の上位桁の数値をアサーションすることができます. + </para> + <para> + この処理は,変数computedとexpectedがdoubleの行列である場合にのみ + 動作します. + その他の場合にはエラーが発生します. + </para> + <para> + 比較がcomputedがexpectedにほぼ等しくないことを示す場合, + <itemizedlist> + <listitem> + <para> + errmsg出力変数が使用されない場合, + エラーが生成され, + </para> + </listitem> + <listitem> + <para> + errmsg出力変数が使用される場合, + エラーは生成されません. + </para> + </listitem> + </itemizedlist> + </para> + <para> + 値を比較する過程において, + %nan, +%inf, -%inf と残りの値を分割します. + nan値の比較はできません. + これが %nan 値がある場所の添字を比較する理由です. + 無限大の値の差をとった場合, + %nan 値が生成されます. + これが +%inf 値がある場所の添字を比較する理由です. + -%inf 値の場合も同様です. + よって, nanおよび無限大を除く値が実際に比較されます. + </para> + <para> + デフォルトの comptype="element" オプションは + 要素毎の比較,すなわち, + 行列の全ての要素がほぼ等しいこと,を行います. + comptype="matrix" オプションは行列全体を比較し, + 行列の差のノルムが使用されます. + </para> + <para> + 一般に,相対許容誤差を機械イプシロン %eps の倍数に設定する + 必要があります. + 相対許容誤差は可能な範囲で最も小さい大きさとする必要が + あります. + つまり, 可能な限り許容誤差を精度良く設定する必要があります. + 相対許容誤差を設定する手順では, + 以下の値を順番に使用することを推奨します : + 0 (全ての桁が正しい), %eps, 10*%eps, 100*%eps, 1.e3*%eps, 1.e4*%eps, ..., + 1.e17*%eps (全ての桁が正しくない). + この例としては以下を参照ください. + </para> + <para> + この関数は複素数を処理します. + まず入力引数の実部を比較します. + これが失敗した場合,ただちにリターンします. + 成功した場合,入力引数の虚部が比較されます. + </para> + <para> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +// 成功する比較. +// 相対誤差 : +assert_checkalmostequal ( 1 , 1 ); +assert_checkalmostequal ( 1 , 1 , %eps ); +assert_checkalmostequal ( ones(10,1) , ones(10,1) , %eps ); +// 絶対誤差 : +assert_checkalmostequal ( 1.23456789123456789e-30 , 0 , 0 , 1.e-10 ); +assert_checkalmostequal ( [1 %nan], [1 %nan] , 0 , %eps ); +// 失敗する比較. +// エラーメッセージを出力 : +assert_checkalmostequal ( 1 , 2 , %eps ); +// エラーメッセージを出力 : +flag = assert_checkalmostequal ( 1 , 2 , %eps ) +// エラーメッセージは出力されない : +[flag,errmsg] = assert_checkalmostequal ( 1 , 2 , %eps ) +assert_checkalmostequal ( 1 , [2 3] , %eps ); +assert_checkalmostequal ( [%nan 1], [1 %nan] , %eps ); +assert_checkalmostequal ( 1 + 5 * %eps , 1 , %eps ); +assert_checkalmostequal ( 1.23456789123456789e-30 , 1.3e-30 , %eps ); +// expectedがゼロでない場合, +// 相対誤差の許容値を %eps の倍数とする必要があります. +// 以下のテストは成功し, 最大実現可能な精度に対して +// 11桁以下が失われたことが示されます. +assert_checkalmostequal ( 1.23456 , 1.23457 , 1.e11*%eps ); +// 相対および絶対許容誤差を交換できません. +// 以下のテストはパスします: 予測値が0であるため, +// 絶対許容誤差を使用します. +assert_checkalmostequal ( 1.23456789e-30 , 0 , 0 , 1.e-10 ); +// 以下のテストは失敗します: 相対許容誤差を使用します. +assert_checkalmostequal ( 0 , 1.23456789e-30 , 1.e-10 ); +// 許容誤差を可能な限りタイトに設定する必要があります. +// 許容誤差が指定した数に対して小さすぎるため,以下のテストは失敗します. +assert_checkalmostequal ( 1.23456 , 1.23457 , %eps ); +// 共通の桁数を取得します: +assert_computedigits(1.23456 , 1.23457) +// 5.09を返します... +// 精度の判定を行い, 受け入れ可能であると結論付けます: +assert_checkalmostequal ( 1.23456 , 1.23457 , 1.e-5 ); +// assert_checkalmostequalの実用的な使用例を示します. +// ヒルバート行列に基づく,平均的に悪条件の線形方程式の +// システムを解きます. +n = 6; +// 予測値を設定します. +expected = ones(n,1); +A = testmatrix("hilb",n); +// 行列の条件数を計算します : ~10^8 +ceil(log10(cond(A))) +// これは,理論的に失われる桁数が 8 であることを意味します, +// 指定した A と expected から右辺が計算されます. +b = A * expected; +// この場合, 部分ピボット選択付きのガウスアルゴリズムが +// 使用されます. +computed = A\b; +// 以下のテストは失敗します: いくつかの桁が失われます. +assert_checkalmostequal(computed,expected,%eps) +// 共通する実際の桁数を計算します: 10から12桁 +assert_computedigits(computed, expected) +// この計算を受け入れます. +// 以下のテストはパスします. +assert_checkalmostequal(computed,expected,1.e5*%eps); +// 以下の例は comptype="element" と "matrix" の差異を示します. +// 以下のテストはパスしません. +assert_checkalmostequal ( [1 1.e5] , [2 1.e5] , 1.e-3 ) +// 以下のテストは行列に基づく比較ではパスします. +assert_checkalmostequal ( [1 1.e5] , [2 1.e5] , 1.e-3 , [] , "matrix" ) +// 以下のテストはパスします. +// IEEE値を考慮することは容易ではありません. +[flag,errmsg] = assert_checkalmostequal ( [1.2345 %inf -%inf %nan] , [1.2346 %inf -%inf %nan] , 1.e-4 ) +// この関数は複素数を考慮します. +// 以下のテストはパスします. +assert_checkalmostequal ( 1+%i , 1+(1+1.e-4)*%i , 1.e-3 , [], "element" ); +// 以下のテストは失敗します. +assert_checkalmostequal ( 1+%i , 1+(1+1.e-4)*%i , 1.e-5 , [], "element" ); + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_checkequal.xml b/modules/development_tools/help/ja_JP/assert/assert_checkequal.xml new file mode 100755 index 000000000..51d98b390 --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_checkequal.xml @@ -0,0 +1,120 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkequal" xml:lang="ja"> + <refnamediv> + <refname>assert_checkequal</refname> + <refpurpose>計算値と予測値が等しいことを確認する.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + assert_checkequal ( computed , expected ) + flag = assert_checkequal ( computed , expected ) + [flag,errmsg] = assert_checkequal ( computed , expected ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>computed:</term> + <listitem> + <para>計算結果</para> + </listitem> + </varlistentry> + <varlistentry> + <term>expected :</term> + <listitem> + <para>予測された結果</para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para>1行1列の論理値行列で, 計算値が予測値と等しい場合に%t,そうでない場合に%f + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para>1行1列の文字列行列で,エラーメッセージ. + flag==%t の場合, errormsg==""となります. + flag==%f の場合, errmsgにはエラーメッセージが出力されます. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + computedとexpectedが等しい場合,そのまま実行されます. + </para> + <para> + 入力引数の型が共に1 (すなわち実数行列)の場合, + nan以外の値が等しいことが確認されます. + </para> + <para> + まず実部を確認し,それが等しい場合に虚部を確認します. + </para> + <para> + 比較がcomputedがexpectedに等しくないことを示す場合, + <itemizedlist> + <listitem> + <para> + errmsg出力変数が使用されない場合,エラーが生成され, + </para> + </listitem> + <listitem> + <para> + errmsg出力変数が使用される場合,エラーは生成されません. + </para> + </listitem> + </itemizedlist> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +// 成功するテスト +assert_checkequal ( %T , %T ); +flag = assert_checkequal ( list() , list() ); +[flag , errmsg] = assert_checkequal ( [%T %F], [%T %F] ); +assert_checkequal ( %nan , %nan ); +// 失敗するテスト +assert_checkequal ( %F , %T ); +flag = assert_checkequal ( %F , %T ); +// エラーは発生しません : +[flag , errmsg] = assert_checkequal ( %F , %T ) +assert_checkequal ( [1 2], [3 4] ) +assert_checkequal ( 1 , [2 3] ) +assert_checkequal ( 1 , "b" ) + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> + <refsection> + <title>参考文献</title> + <para>"Automated Software Testing for Matlab", Steven Eddins, 2009</para> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_checkerror.xml b/modules/development_tools/help/ja_JP/assert/assert_checkerror.xml new file mode 100755 index 000000000..57d351750 --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_checkerror.xml @@ -0,0 +1,270 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkerror" xml:lang="ja"> + <refnamediv> + <refname>assert_checkerror</refname> + <refpurpose>命令が予測したエラーを発生することを確認する. + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + flag = assert_checkerror ( instr , expectedmsg ) + flag = assert_checkerror ( instr , expectedmsg , expectederrnb ) + flag = assert_checkerror ( instr , expectedmsg , expectederrnb , a1, ... ) + [flag,errmsg] = assert_checkerror ( ... ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>instr:</term> + <listitem> + <para>1行1列の文字列行列, 評価する式</para> + </listitem> + </varlistentry> + <varlistentry> + <term>expectedmsg :</term> + <listitem> + <para> + 文字列または文字列ベクトル,生成するエラーメッセージ + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>expectederrnb :</term> + <listitem> + <para> + 1行1列のdouble,整数値,エラー番号の行列 + (デフォルト: expectederrnb=[]). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>a1 :</term> + <listitem> + <para> + <literal>msprintf</literal> 関数に指定する, + オプションのローカライズ用引数. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para>1行1列の論理値行列,正しいエラーメッセージが生成された場合に %t , + そうでない場合に %f + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> + 1行1列の文字列行列で,エラーメッセージ. + flag==%t の場合, errormsg==""となります. + flag==%f の場合, errmsgにはエラーメッセージが出力されます. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + 式がエラーを発生しない場合, + <literal>assert_checkerror</literal> はエラーを発生します. + 評価された式が予想されたエラーメッセージを生成する場合,そのまま実行されます. + </para> + <para> + エラーメッセージ<literal>expectedmsg</literal>が指定され, + 空の行列 <literal>[]</literal>でない場合, + 生成されたエラーメッセージが指定されたものに一致することが確認されます. + エラー番号<literal>expectederrnb</literal>が指定され, + 空の行列 <literal>[]</literal>でない場合, + 生成されたエラー番号が指定されたものに一致することが確認されます. + エラーメッセージ<literal>expectedmsg</literal>および + エラー番号 <literal>expectederrnb</literal>を + 同時に空の行列<literal>[]</literal>とすることはできません: + 少なくとも一つを指定する必要があります. + </para> + <para> + 文字列の一致では文字列が厳密に等しいことが確認されます: + パターンまたは正規表現は使用できません. + </para> + <para> + エラーメッセージが予測値と異なるか,エラー番号が異なる場合, + <itemizedlist> + <listitem> + <para> + errmsg出力変数が指定されない場合,エラーが生成され, + </para> + </listitem> + <listitem> + <para> + errmsg出力変数が指定される場合,エラーは生成されません. + </para> + </listitem> + </itemizedlist> + </para> + <para> + この関数の目的は,簡単なフレームワークによりエラーのケースを + 確認できるようにすることです. + ある関数のエラーメッセージを確認することには以下のような利点があります: + <itemizedlist> + <listitem> + <para> + 必要な時に正しいエラーが生成されることを確認する, + </para> + </listitem> + <listitem> + <para> + エラーメッセージが正しく整形されていることを確認する, + </para> + </listitem> + <listitem> + <para> + エラーメッセージが正しくローカライズされていることを確認する. + </para> + </listitem> + </itemizedlist> + </para> + <para> + 予測されるメッセージをローカライズされたメッセージとすることができます. + この場合,メッセージは<literal>gettext</literal>関数の出力と + 比較され,ローカルな言語に依存します. + オプション引数<literal>a1</literal>をこの目的, + 例えばローカライズされたメッセージを整形するために,使用できます. + 全てのオプション引数 + <literal>a1</literal>, + <literal>a2</literal>, ... は計算されたエラーメッセージと比較する前に自動的に + <literal>msprintf</literal>関数に指定されます. + </para> + </refsection> + <refsection> + <title>例</title> + <para> + <literal>assert_checkerror</literal>関数を使用する複数の例を示します. + まずテストする関数を定義する必要があります. + </para> + <para> + 以下の関数<literal>f</literal>は, + 入力引数の数が間違っているか<literal>x</literal>の型が間違っている + 場合にエラーを発生します. + </para> + <programlisting role="example"><![CDATA[ +function y = f(x) + [lhs, rhs] = argn() + if ( rhs <> 1 ) then + lstr = gettext("%s: Wrong number of input argument: %d expected.\n") + errmsg = msprintf ( lstr , "f" , 1 ) + error(errmsg) + end + if ( typeof(x) <> "constant" ) then + lstr = gettext("%s: Wrong type for argument #%d: Matrix expected.\n") + errmsg = msprintf ( lstr , "f" , 1 ) + error(errmsg,123456789) + end + y = x +endfunction + ]]></programlisting> + <para> + 我々のタスクは,この関数により生成されたエラーメッセージを確認することです. + 以下の2つのテストをパスします: + エラーメッセージが予測されたものである. + ローカライズされたメッセージとオプションの + パラメータ<literal>"f"</literal>(関数名)と + <literal>1</literal>(入力引数の添字)のみを指定し, + <literal>assert_checkerror</literal>がローカライズ化を管理するようにします. + これらの2つのオプションパラメータは, + メッセージを整形し, + "%s" および "%d" フォーマットを実際の値に変換する際に使用されます. + </para> + <programlisting role="example"><![CDATA[ +lcl1 = "%s: Wrong number of input argument: %d expected.\n"; +assert_checkerror ( "y = f()" , lcl1 , [] , "f" , 1); + +lcl2 = "%s: Wrong type for argument #%d: Matrix expected.\n"; +assert_checkerror ( "y = f(""a"")" , lcl2 , [] , "f" , 1); + ]]></programlisting> + <para> + ここで,カレントのロケール言語が英語であると仮定すると, + 以下のコードを正しく使用できます. + しかし,例えばカレントのロケールがフランス語である場合に失敗するため, + これは推奨される手法ではありません. + </para> + <programlisting role="example"><![CDATA[ +assert_checkerror ( "y = f()" , "f: Wrong number of input argument: 1 expected." ); + ]]></programlisting> + <para>以下のテストでは, エラー番号も確認します.</para> + <programlisting role="example"><![CDATA[ +lcl1="%s: Wrong number of input argument: %d expected.\n"; +assert_checkerror ( "y=f()" , lcl1 , 10000 , "f" , 1); + +lcl2 = "%s: Wrong type for argument #%d: Matrix expected.\n"; +assert_checkerror ( "y=f(""a"")" , lcl2 , 123456789 , "f" , 1); + ]]></programlisting> + <para>以下の2つのテストは失敗します.</para> + <programlisting role="example"><![CDATA[ +assert_checkerror ( "y = f()" , "oups" ); +msg1 = msprintf(gettext("%s: Wrong number of input argument: %d expected.\n"), "f", 1); +assert_checkerror ( "y = f()" , msg1 , 12 ); + ]]></programlisting> + <para> + errmsgが出力引数に指定された場合,以下の例のように,エラーが生成されます. + 変数<literal>flag</literal> および <literal>errmsg</literal>の内容に + 注意してください. + </para> + <programlisting role="example"><![CDATA[ +// パスするテスト: flag は %t, errmsg は空 +msg1 = msprintf(gettext("%s: Wrong number of input argument: %d expected.\n"), "f", 1); +[flag, errmsg] = assert_checkerror ( "y = f()" , msg1 ) +// 失敗するテスト: flag は %f, errmsg は空でない +[flag, errmsg] = assert_checkerror ( "y = f()" , "oups" ) + ]]></programlisting> + <para> + 以下の2つのテストのメッセージはローカライズされており, + カレントの言語が何であっても動作します. + オプションのパラメータ<literal>a1</literal>を使用する代わりに + 長くはなりますが,完全に有効なコードである + ローカライズされたメッセージを直接使用します. + </para> + <programlisting role="example"><![CDATA[ +msg1 = msprintf(gettext("%s: Wrong number of input argument: %d expected.\n"), "f", 1); +assert_checkerror ( "y = f()" , msg1 ); +msg2 = msprintf(gettext("%s: Wrong type for argument #%d: Matrix expected.\n"), "f", 1); +assert_checkerror ( "y = f(""a"")" , msg2 ); + ]]></programlisting> + <para> + エラー番号を確認したいがエラーメッセージは確認したくない場合がありえます. + 以下のスクリプトは, + 最初の引数が doubleの行列でない場合に + 生成されるエラー番号が 123456789 であることのみを + 確認します: エラーメッセージは確認しません. + </para> + <programlisting role="example"><![CDATA[ +assert_checkerror("f(""foo"")", [], 123456789); + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました</revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_checkfalse.xml b/modules/development_tools/help/ja_JP/assert/assert_checkfalse.xml new file mode 100755 index 000000000..ca305a6e1 --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_checkfalse.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkfalse" xml:lang="ja"> + <refnamediv> + <refname>assert_checkfalse</refname> + <refpurpose>条件が false であることを確認する.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + flag = assert_checkfalse ( condition ) + flag = assert_checkfalse ( condition ) + [flag,errmsg] = assert_checkfalse ( condition ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>condition:</term> + <listitem> + <para> 論理値の行列</para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para> + 1行1列の論理値行列, 条件が falseの場合に %t, + そうでない場合に %f + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> + 1行1列の文字列行列,エラーメッセージ. + flag==%t の場合, errmsg="". + flag==%f の場合, errmsgにはエラーメッセージが代入されます. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + <literal>condition</literal> の全エントリがfalseの場合に + そのまま実行されます. + </para> + <para> + <literal>condition</literal>のエントリのどれかがtrueの場合に + エラーが発生します. + <literal>condition</literal>が論理値でない場合にエラーが発生します. + </para> + <para> + conditionのエントリのどれかがtrueの場合, + <itemizedlist> + <listitem> + <para> + 出力変数errmsgが使用されない場合,エラーが出力され, + </para> + </listitem> + <listitem> + <para> + 出力変数errmsgが使用される場合,エラーは出力されません. + </para> + </listitem> + </itemizedlist> + </para> + <para> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +// テストはパスする +assert_checkfalse ( %f ); +flag = assert_checkfalse ( %f ) +[flag,errmsg] = assert_checkfalse ( %f ) +[flag,errmsg] = assert_checkfalse ( [%f %f] ); +// テストは失敗する +assert_checkfalse ( [%t %f] ); +flag = assert_checkfalse ( [%t %f] ) +// エラーは生成されない +[flag,errmsg] = assert_checkfalse ( [%t %f] ) +// 誤ったコール +assert_checkfalse ( "a" ) + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_checkfilesequal.xml b/modules/development_tools/help/ja_JP/assert/assert_checkfilesequal.xml new file mode 100755 index 000000000..de3ea6f6c --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_checkfilesequal.xml @@ -0,0 +1,224 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkfilesequal" xml:lang="ja"> + <refnamediv> + <refname>assert_checkfilesequal</refname> + <refpurpose>2つのファイルが等しいことを確認する.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + flag = assert_checkfilesequal ( filecomp , fileref ) + flag = assert_checkfilesequal ( filecomp , fileref , compfun ) + [flag,errmsg] = assert_checkfilesequal ( ... ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>filecomp :</term> + <listitem> + <para> 1行1列の文字列行列, 計算されたファイル.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>fileref :</term> + <listitem> + <para> 1行1列の文字列行列, 基準ファイル.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>compfun :</term> + <listitem> + <para> 関数またはリスト, + 比較用関数 (デフォルト:compfun = []). + 比較用関数が使用されない場合, + 等価演算子 "==" が使用されます. + 詳細については以下を参照ください. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para> + 1行1列の論理値行列, + computedがexpectedに近い場合に %t, + そうでない場合に %f + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> + 1行1列の文字列行列, エラーメッセージ. + flag==%t の場合, errmsg="". + flag==%f の場合, errmsgにエラーメッセージが代入されます. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + ファイルが等しい場合,そのまま実行されます. + filecompまたはfilerefが存在しない場合,エラーが発生します. + ファイルの内容が等しくない場合,エラーが発生します. + </para> + <para> + ファイルが等しくない場合, + <itemizedlist> + <listitem> + <para> + 出力変数errmsgが使用されない場合,エラーが発生し, + </para> + </listitem> + <listitem> + <para> + 出力変数errmsgが使用された場合,エラーは発生しません. + </para> + </listitem> + </itemizedlist> + </para> + <para> + 比較用関数compfunが関数の場合, + ヘッダareequal = compfun ( txtcomp , txtref )を有する必要があります. + ただし, txtcomp は computed ファイルの内容, + txtref は基準ファイルの内容, + areequalは論理値です. + 2つの内容が等しい場合,論理値areequalはtrueとなります. + compfunがリストの場合,リスト(cf,a1,a2,...)とする必要があります. + ただし, cf は比較関数で, 引数 a1, a2 がcfの呼び出し手順の最後に + 自動的に付加されます. + </para> + <para> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +// +// テスト用のデータを準備 +// fileref1 : 3行分のテキスト +// filecomp1 : == fileref1 +// filecomp2 : <> fileref1 +fileref1 = fullfile(TMPDIR,"fileref.txt"); +txt1 = [ +"Line #1" +"Line #2" +"Line #3" +]; +fd = mopen(fileref1,"w"); +mputl(txt1,fd); +mclose(fd); +filecomp1 = fullfile(TMPDIR,"filecomp1.txt"); +fd = mopen(filecomp1,"w"); +mputl(txt1,fd); +mclose(fd); +filecomp2 = fullfile(TMPDIR,"filecomp2.txt"); +txt2 = [ +"Line #1" +"Line #4" +"Line #3" +]; +fd = mopen(filecomp2,"w"); +mputl(txt2,fd); +mclose(fd); +// パスするテスト +flag = assert_checkfilesequal ( filecomp1 , fileref1 ) +[flag,errmsg] = assert_checkfilesequal ( filecomp1 , fileref1 ) +// 失敗: filecomp2 <> fileref1 +// エラーが発生 +flag = assert_checkfilesequal ( filecomp2 , fileref1 ) +// エラーは発生しない +[flag,errmsg] = assert_checkfilesequal ( filecomp2 , fileref1 ) +// テスト用のデータを準備 +// fileref2 == filecomp3, コメント行を無視した場合 +// fileref2 <> filecomp4, コメント行を無視した場合 +// コメントはファイルの異なる位置に挿入されることに注意してください: +// ある時は先頭, ある時は中央. +fileref2 = fullfile(TMPDIR,"fileref2.txt"); +txt = [ +"// bla 2" +"Line #1" +"// bla 2" +"Line #2" +"Line #3" +]; +fd = mopen(fileref2,"w"); +mputl(txt,fd); +mclose(fd); +filecomp3 = fullfile(TMPDIR,"filecomp3.txt"); +txt = [ +"Line #1" +"// bla 5168" +"Line #2" +"Line #3" +"// bla oups" +]; +fd = mopen(filecomp3,"w"); +mputl(txt,fd); +mclose(fd); +filecomp4 = fullfile(TMPDIR,"filecomp4.txt"); +txt = [ +"// bla 3" +"Line #1" +"Line #4" +"// bla 5168" +"Line #3" +"// bla oups" +]; +fd = mopen(filecomp4,"w"); +mputl(txt,fd); +mclose(fd); +// コメント行を無視する比較用関数でテスト +function otxt = myfilter ( itxt ) +nr = size(itxt,"r") +// 形式 "// blabla" のコメント行用のパターン +pattern = "/\/\/.*/" +k = 1 +for i = 1 : nr +start = regexp(itxt(i),pattern) +if ( start == [] ) then +otxt(k) = itxt(i) +k = k + 1 +end +end +endfunction +function areequal = mycompfun ( ctxt , etxt ) +ctxt = myfilter ( ctxt ) +etxt = myfilter ( etxt ) +areequal = ( ctxt == etxt ) +endfunction +// +// パスするテスト +[flag,errmsg] = assert_checkfilesequal ( filecomp3 , fileref2 , mycompfun ) +// 失敗するテスト +[flag,errmsg] = assert_checkfilesequal ( filecomp4 , fileref2 , mycompfun ) + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_checktrue.xml b/modules/development_tools/help/ja_JP/assert/assert_checktrue.xml new file mode 100755 index 000000000..65857decf --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_checktrue.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checktrue" xml:lang="ja"> + <refnamediv> + <refname>assert_checktrue</refname> + <refpurpose>条件がtrueであることを確認する.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + flag = assert_checktrue ( condition ) + flag = assert_checktrue ( condition ) + [flag,errmsg] = assert_checktrue ( condition ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>condition:</term> + <listitem> + <para> 論理値の行列</para> + </listitem> + </varlistentry> + <varlistentry> + <term>flag :</term> + <listitem> + <para> + 1行1列の論理値行列, 条件がtrueの場合に %t, + そうでない場合に %f + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>errmsg :</term> + <listitem> + <para> + 1行1列の文字列行列,エラーメッセージ. + flag==%t の場合, errmsg="". + flag==%f の場合, errmsgにはエラーメッセージが代入されます. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + <literal>condition</literal> の全エントリがtrueの場合に + そのまま実行されます. + </para> + <para> + <literal>condition</literal>のエントリのどれかがfalseの場合に + エラーが発生します. + <literal>condition</literal>が論理値でない場合にエラーが発生します. + </para> + <para> + conditionのエントリのどれかがfalseの場合, + <itemizedlist> + <listitem> + <para> + 出力変数errmsgが使用されない場合,エラーが出力され, + </para> + </listitem> + <listitem> + <para> + 出力変数errmsgが使用される場合,エラーは出力されません. + </para> + </listitem> + </itemizedlist> + </para> + <para> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +// パスするテスト +assert_checktrue ( %t ); +flag = assert_checktrue ( %t ) +[flag,errmsg] = assert_checktrue ( %t ) +[flag,errmsg] = assert_checktrue ( [%t %t] ); +// 失敗するテスト +assert_checktrue ( [%t %f] ); +flag = assert_checktrue ( [%t %f] ) +// エラーは出力されません +[flag,errmsg] = assert_checktrue ( [%t %f] ) +// 間違ったコール +assert_checktrue ( "a" ) + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_comparecomplex.xml b/modules/development_tools/help/ja_JP/assert/assert_comparecomplex.xml new file mode 100755 index 000000000..861f738be --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_comparecomplex.xml @@ -0,0 +1,186 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_comparecomplex" xml:lang="ja"> + <refnamediv> + <refname>assert_comparecomplex</refname> + <refpurpose>許容誤差を指定して複素数を比較する.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + order = assert_comparecomplex ( a , b ) + order = assert_comparecomplex ( a , b , reltol ) + order = assert_comparecomplex ( a , b , reltol , abstol ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>a :</term> + <listitem> + <para> + 1行1列のdouble行列,比較する最初の値 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>b :</term> + <listitem> + <para> + 1行1列のdouble行列,比較する2番目の値 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>reltol :</term> + <listitem> + <para> + 1行1列のdouble行列,相対許容誤差 (デフォルト: reltol=sqrt(%eps)). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>abstol :</term> + <listitem> + <para> + 1行1列のdouble行列,絶対許容誤差 (デフォルト: abstol=0). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>order :</term> + <listitem> + <para> + 1行1列のdouble行列,整数値,順番. + aがbにほぼ等しい場合にorder=0, + a < bの場合に order=-1, + a > bの場合に order=+1. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + まず実部,次に虚部を比較します. + 相対および絶対許容誤差による判定を組み合わせることで + 数値的な問題を考慮します. + </para> + <para> + オプションの入力引数が空の行列に等しい場合, + そのデフォルト値に置換されます. + </para> + <para> + 以下のアルゴリズムを使用します. + </para> + <para> + まず実部を比較します.それが等しい場合, + 虚部を比較します. + </para> + <para> + IEEE値を処理し,順番を選択します: -%inf < 0 < %inf < %nan. + どの値も特殊な値でない場合, 以下の条件を使用します: + <programlisting> + cond = ( abs(a-b) <= reltol * max(abs(a),abs(b)) + abstol ) + </programlisting> + </para> + <para> + このアルゴリズムはソート用アルゴリズムの中で使用される + よう設計されています. + これにより, + 複素数のdoubleの行列を出力する関数の出力に関連した + 移植性の問題を考慮することができます. + このアルゴリズムがソート用関数に組み込まれた場合, + 順番をオペレーティング・システム,コンパイラまたは + (値ではなく)順番を変更する他の問題に依存させずに, + 一貫してソートされた行列を出力することができるようになります. + </para> + <para> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +// 実数値を比較 +assert_comparecomplex ( 1 , -1 ) // 1 +assert_comparecomplex ( -1 , 1 ) // -1 +assert_comparecomplex ( 1 , 1 ) // 0 +// 複素数を比較 #1 +assert_comparecomplex ( 1+2*%i , 1+3*%i ) // -1 +assert_comparecomplex ( 1+3*%i , 1+2*%i ) // 1 +assert_comparecomplex ( 1+2*%i , 1+2*%i ) // 0 +// 複素数を比較 #2 +assert_comparecomplex ( 1+%i , -1+%i ) // 1 +assert_comparecomplex ( -1+%i , 1+%i ) // -1 +assert_comparecomplex ( 1+%i , 1+%i ) // 0 +[order,msg] = assert_comparecomplex ( 1+%i , 1+%i ) +// 許容誤差を指定して比較: 等号の場合 +assert_comparecomplex ( 1.2345+%i , 1.2346+%i , %eps , 1.e-3 ) // 0 +assert_comparecomplex ( 1.2345+%i , 1.2346+%i , 1.e12*%eps , 0 ) // 0 +assert_comparecomplex ( 1+1.2345*%i , 1+1.2347*%i , %eps , 1.e-3 ) // 0 +assert_comparecomplex ( 1+1.2345*%i , 1+1.2347*%i , 1.e12*%eps , 0 ) // 0 +// より実際的なデータの比較 +x = [ +-0.123452 - 0.123454 * %i +-0.123451 + 0.123453 * %i +0.123458 - 0.123459 * %i +0.123456 + 0.123457 * %i +]; +// 上位4桁以下を考慮 +for i = 1 : size(x,"*")-1 +order = assert_comparecomplex ( x(i) , x(i+1) , 1.e-4 ); +mprintf("compare(x(%d),x(%d))=%d\n",i,i+1,order) +end +// バグ#415からのデータを比較 +x = [ +-1.9914145 +-1.895889 +-1.6923826 +-1.4815461 +-1.1302576 +-0.5652256 - 0.0655080 * %i +-0.5652256 + 0.0655080 * %i +0.3354023 - 0.1602902 * %i +0.3354023 + 0.1602902 * %i +1.3468911 +1.5040136 +1.846668 +1.9736772 +1.9798866 +]; +// 上位4桁以下を考慮 +for i = 1 : size(x,"*")-1 +order = assert_comparecomplex ( x(i) , x(i+1) , 1.e-5 ); +mprintf("compare(x(%d),x(%d))=%d\n",i,i+1,order) +end + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> + <refsection> + <title>参考文献</title> + <para>http://gitweb.scilab.org/?p=scilab.git;a=blob;f=scilab/modules/polynomials/tests/nonreg_tests/bug_415.tst;h=0c716a3bed0dfb72c831972d19dbb0814dffde2b;hb=HEAD</para> + <para>http://gitweb.scilab.org/?p=scilab.git;a=blob_plain;f=scilab/modules/cacsd/tests/nonreg_tests/bug_68.tst;h=920d091d089b61bf961ea9e888b4d7d469942a14;hb=4ce3d4109dd752fce5f763be71ea639e09a12630</para> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_computedigits.xml b/modules/development_tools/help/ja_JP/assert/assert_computedigits.xml new file mode 100755 index 000000000..57e2bea3b --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_computedigits.xml @@ -0,0 +1,147 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_computedigits" xml:lang="ja"> + <refnamediv> + <refname>assert_computedigits</refname> + <refpurpose>計算結果の上位桁数を返す.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + d = assert_computedigits ( computed , expected ) + d = assert_computedigits ( computed , expected , basis ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>computed :</term> + <listitem> + <para> doubleの行列, 計算値</para> + </listitem> + </varlistentry> + <varlistentry> + <term>expected :</term> + <listitem> + <para> doubleの行列, 予測値</para> + </listitem> + </varlistentry> + <varlistentry> + <term>basis :</term> + <listitem> + <para> 1行1列のdoubleの行列, 整数値, 基底 (デフォルトの基底=10)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>d :</term> + <listitem> + <para> doubleの行列, 上位桁数.</para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + 以下の式により非ゼロの結果の予測値に対する + 計算結果の上位桁数を計算します: + </para> + <para> + <latex> + \begin{eqnarray} + d = - \frac{\log_{10} ( r )}{\log_{10}(basis)} + \end{eqnarray} + </latex> + </para> + <para> + ただし,相対誤差は以下により定義されます + </para> + <para> + <latex> + \begin{eqnarray} + r = \frac{|computed - expected|}{|expected|} + \end{eqnarray} + </latex> + </para> + <para> + オプションのパラメータが空の行列[]に等しい場合, + そのデフォルト値に置換されます. + </para> + <para> + 上位桁数は dmin = 0 と + dmax = -log10(2^(-53)) (約 15.95 ~ 16 ) の範囲となります. + 基底2の場合,上位桁数は 53です. + </para> + <para> + expectedがcomputedに等しい場合, d は最大値,すなわちdmax,に + 設定されます. + そうでない場合,expectedがゼロでcomputedがゼロでない場合, + d はその最小値,すなわち dmin=0に設定されます. + </para> + <para> + 相対誤差は予測値に基づいているため, + computedとexpectedの値は交換できません. + </para> + <para> + 計算は値の実部と虚部に分割されます. + 桁数の戻り値は,実部と虚部の桁数の最小値です. + </para> + <para> + TODO : assert_digits ( computed , expected , dmin ) 関数の中で computedigitsを使用 + </para> + <para> + TODO : + 比較 "matrix" (現在は "element")のためのcomptypeオプションを追加 + </para> + <para> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +d = assert_computedigits ( 1 , 1 ) // d ~ 16 +d = assert_computedigits ( 1 , 1 , 2 ) // d = 53 +d = assert_computedigits ( 0 , 0 ) // d ~ 16 +d = assert_computedigits ( 1 , 0 ) // d = 0 +d = assert_computedigits ( 0 , 1 ) // d = 0 +d = assert_computedigits ( 3.1415926 , %pi ) // d ~ 8 +d = assert_computedigits ( 3.1415926 , %pi , 2 ) // d ~ 26 +d = assert_computedigits ( [0 0 1 1] , [0 1 0 1] ) // d ~ [16 0 0 16] +d = assert_computedigits(ones(3,2),ones(3,2)) // d ~ 16 * ones(3,2) +d = assert_computedigits(1.224646799D-16,8.462643383D-18) // d = 0 +// IEEE値を確認 +// d ~ [16 0 0 0] +d = assert_computedigits([%nan %nan %nan %nan],[%nan %inf -%inf 0]) +// d ~ [0 16 0 0] +d = assert_computedigits([%inf %inf %inf %inf],[%nan %inf -%inf 0]) +// d = [0 0 16 0] +d = assert_computedigits([-%inf -%inf -%inf -%inf],[%nan %inf -%inf 0]) +// d = [0 0 0 16] +d = assert_computedigits([0 0 0 0],[%nan %inf -%inf 0]) +// 複素数を確認 +d = assert_computedigits ( 1.2345 + %i*6.7891 , 1.23456789 + %i*6.789123456 ) // d ~ 4 + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_cond2reltol.xml b/modules/development_tools/help/ja_JP/assert/assert_cond2reltol.xml new file mode 100755 index 000000000..6dc894f9b --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_cond2reltol.xml @@ -0,0 +1,162 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_cond2reltol" xml:lang="ja"> + <refnamediv> + <refname>assert_cond2reltol</refname> + <refpurpose>条件数から計算した相対誤差を提案する.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + rtol = assert_cond2reltol ( condition ) + rtol = assert_cond2reltol ( condition , offset ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>condition :</term> + <listitem> + <para> + doubleの行列,条件数. + 条件数は厳密に正とする必要があります. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>offset :</term> + <listitem> + <para> + doubleの行列, 必要な10進桁数のためのシフト + (デフォルト: offset=0). + 例えば,offset=1は必要な精度を増加させ + (相対許容誤差を10^-1倍に減らします), + offset=-1は必要な精度を減らします + (相対許容誤差を10^1倍に増やします). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>rtol :</term> + <listitem> + <para> + doubleの行列, 相対許容誤差. + 相対許容誤差は厳密に正で, 1より小さい数です + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + 条件数に基づき,対応する相対許容誤差を返します. + </para> + <para> + オプションのパラメータが空の行列 [] に等しい場合, + そのデフォルト値を設定します. + </para> + <para> + この相対許容誤差は単なる推奨値であることを強調しておきます. + 代わりに,より小さいまたは大きな相対許容誤差を使用する + 正当な理由がある場合がありえます. + </para> + <para> + <itemizedlist> + <listitem> + <para> + 悪条件の問題においても, + 正確な計算が可能な素晴らしいアルゴリズムがある場合を + 考えてみましょう. + この場合,より高い精度(正のオフセット)が必要となります. + </para> + </listitem> + <listitem> + <para> + 性能と精度のトレードオフがあり,性能が勝る場合について + 考えてみましょう. + この場合, より劣る精度(負のオフセット)が必要となります. + </para> + </listitem> + </itemizedlist> + </para> + <para> + スカラー入力引数は全て他の入力引数と同じ大きさのdoubleの + 行列に展開されます. + </para> + <para> + 必要な桁数 d を計算した後,相対許容誤差 10^-d を計算します. + </para> + <para> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +assert_cond2reltol ( 0 ) // 1.110D-16 +assert_cond2reltol ( 1 ) // 1.110D-16 +assert_cond2reltol ( 1.e1 ) // 1.110D-15 +assert_cond2reltol ( 1.e2 ) // 1.110D-14 +assert_cond2reltol ( 1.e3 ) // 1.110D-13 +assert_cond2reltol ( 1.e16 ) // 1 +assert_cond2reltol ( 1.e17 ) // 1 +assert_cond2reltol ( 1.e18 ) // 1 +// 行列入力. +condition = [0,1,10,100,1000,1.D13,1.D14,1.D15,1.D16,1.D17,1.D18]; +expected = [1.110D-16 1.110D-16 1.110D-15 1.110D-14 1.110D-13 0.0011102 0.0111022 0.1110223 1. 1. 1.]; +assert_cond2reltol ( condition ) +// オフセットを使用 +// Negative offset : require less accuracy +assert_cond2reltol ( 1.e2 , [0 -1] ) // [1.1D-14 1.1D-13] +// 正のオフセット : より高い精度を必要とします +// オフセットの影響を調べます +assert_cond2reltol ( 1.e2 , [0 1 2 3] ) // [1.1D-14 1.1D-15 1.1D-16 1.1D-16] +// 負のオフセット +// オフセットの影響を調べます +assert_cond2reltol ( 1.e14 , [0 -1 -2 -3] ) // [1.1D-02 1.1D-01 1 1] +// 条件数に対して相対許容誤差をプロット +condition = logspace(0,18,1000); +r = assert_cond2reltol ( condition ); +plot(condition,r) +h=gcf(); +h.children.log_flags="lln"; +h.children.children.children.thickness=4; +xt = h.children.x_ticks; +xt.locations = 10^(0:2:18)'; +xt.labels = ["10^0";"10^2";"10^4";"10^6";"10^8";"10^10";"10^12";"10^14";"10^16";"10^18"]; +h.children.x_ticks=xt; +yt = h.children.y_ticks; +yt.locations = 10^-(0:2:18)'; +yt.labels = ["10^0";"10^-2";"10^-4";"10^-6";"10^-8";"10^-10";"10^-12";"10^-14";"10^-16";"10^-18"]; +h.children.y_ticks=yt; +xtitle("Relative tolerance","Condition","Relative tolerance"); +r = assert_cond2reltol ( condition , +3 ); +plot(condition,r,"r") +r = assert_cond2reltol ( condition , -3 ); +plot(condition,r,"g") +legend(["Offset=0","Offset=+3","Offset=-3"]); + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_cond2reqdigits.xml b/modules/development_tools/help/ja_JP/assert/assert_cond2reqdigits.xml new file mode 100755 index 000000000..08129b2b7 --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_cond2reqdigits.xml @@ -0,0 +1,189 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_cond2reqdigits" xml:lang="ja"> + <refnamediv> + <refname>assert_cond2reqdigits</refname> + <refpurpose>指定した条件数に必要な桁数を提案する.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + d = assert_cond2reqdigits ( condition ) + d = assert_cond2reqdigits ( condition , offset ) + d = assert_cond2reqdigits ( condition , offset , b ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>condition :</term> + <listitem> + <para> + doubleの行列, 条件数. + 条件数は厳密に正とする必要があります. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>offset :</term> + <listitem> + <para> + doubleの行列, + 必要な基底bの桁数(デフォルト offset = 0). + 例えば, offset=-1 は必要な桁数よりも小さい数 + を出力します(必要な精度を減らす). + offset=1は必要な桁数よりも大きな数を出力します + (必要な精度を増やす). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>b :</term> + <listitem> + <para>doubleの行列, 整数値, b (デフォルト: b = 10).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>d :</term> + <listitem> + <para>doubleの行列, 必要な桁数. + 正の実数で, b=10の場合は0 から 15.95 の範囲, + b=2の場合は0から53の範囲. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + 条件数に基づき,対応する必要な桁数を返します. + </para> + <para> + オプションのパラメータが空の行列[]に等しい場合, + そのデフォルト値に置換されます. + </para> + <para> + この必要な桁数は単なる推奨値であることを強調しておきます. + 代わりに,より小さいまたは大きな桁数を使用する + 正当な理由がある場合がありえます. + </para> + <para> + <itemizedlist> + <listitem> + 悪条件の問題においても, + 正確な計算が可能な素晴らしいアルゴリズムがある場合を + 考えてみましょう. + この場合,より高い精度(正のオフセット)が必要となります. + </listitem> + <listitem> + 性能と精度のトレードオフがあり,性能が勝る場合について + 考えてみましょう. + この場合, より劣る精度(負のオフセット)が必要となります. + </listitem> + </itemizedlist> + </para> + <para> + スカラー入力引数は全て他の入力引数と同じ大きさのdoubleの + 行列に展開されます. + </para> + <para> + アルゴリズムは以下のようになります. + 条件の基底10の指数を計算し,オフセットを引きます. + この数は失われる桁数の予測値を表します. + これを範囲 [0,dmax] に投影します. + ただし, dmax -log10(2^(-53)) は doubleで最大実現可能な + 桁数です. + dmaxと失われる桁数の差から + 必要な桁数 d を計算します. + この結果,相対許容誤差は 10^-d となります. + </para> + <para> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +assert_cond2reqdigits ( 0 ) // 15.95459 +assert_cond2reqdigits ( 1 ) // 15.95459 +assert_cond2reqdigits ( 1.e1 ) // 14.95459 +assert_cond2reqdigits ( 1.e2 ) // 13.95459 +assert_cond2reqdigits ( 1.e3 ) // 12.95459 +assert_cond2reqdigits ( 1.e16 ) // 0 +assert_cond2reqdigits ( 1.e17 ) // 0 +assert_cond2reqdigits ( 1.e18 ) // 0 +// 行列入力. +condition = [0,1,10,100,1000,1.D13,1.D14,1.D15,1.D16,1.D17,1.D18]; +assert_cond2reqdigits ( condition ) +// オフセットを使用 +// 負のオフセット : 必要な桁数を減らす (より低い精度を要求) +assert_cond2reqdigits ( 1.e2 , [0 -1] ) // [13.95459 12.95459] +// 正のオフセット : 必要な桁数を増やす (より高い精度を要求) +// オフセットの影響を調べます. +assert_cond2reqdigits ( 1.e2 , [0 1 2 3] ) // [13.95459 14.95459 15.95459 15.95459] +// 負のオフセット (より低い精度を要求) +// オフセットの影響を調べます. +assert_cond2reqdigits ( 1.e14 , [0 -1 -2 -3] ) // [1.9545898 0.9545898 0. 0.] +// 基底2を使用 +assert_cond2reqdigits ( 0 , [] , 2 ) // 53 +assert_cond2reqdigits ( 1 , [] , 2 ) // 53 +assert_cond2reqdigits ( 1.e1 , [] , 2 ) // 49.678072 +assert_cond2reqdigits ( 1.e2 , [] , 2 ) // 46.356144 +assert_cond2reqdigits ( 1.e3 , [] , 2 ) // 43.034216 +assert_cond2reqdigits ( 1.e16 , [] , 2 ) // 0 +assert_cond2reqdigits ( 1.e17 , [] , 2 ) // 0 +assert_cond2reqdigits ( 1.e18 , [] , 2 ) // 0 +// 条件に基づき必要な10進桁数をプロット +condition = logspace(0,18,1000); +d = assert_cond2reqdigits ( condition ); +plot(condition,d) +h=gcf(); +h.children.log_flags="lnn"; +h.children.children.children.thickness=4; +xt = h.children.x_ticks; +xt.locations = 10^(0:2:18)'; +xt.labels = ["10^0";"10^2";"10^4";"10^6";"10^8";"10^10";"10^12";"10^14";"10^16";"10^18"]; +h.children.x_ticks=xt; +xtitle("Number of required digits","Condition","Required decimal digits"); +// 条件に基づき必要な2進桁数をプロット +condition = logspace(0,18,1000); +d = assert_cond2reqdigits ( condition , [] , 2 ); +plot(condition,d) +h=gcf(); +h.children.log_flags="lnn"; +h.children.children.children.thickness=4; +xt = h.children.x_ticks; +xt.locations = 10^(0:2:18)'; +xt.labels = ["10^0";"10^2";"10^4";"10^6";"10^8";"10^10";"10^12";"10^14";"10^16";"10^18"]; +h.children.x_ticks=xt; +xtitle("Number of required digits","Condition","Required binary digits"); +d = assert_cond2reqdigits ( condition , +10 , 2 ); +plot(condition,d,"r") +d = assert_cond2reqdigits ( condition , -10 , 2 ); +plot(condition,d,"g") +legend(["Offset=0","Offset=+10","Offset=-10"]); + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/assert/assert_generror.xml b/modules/development_tools/help/ja_JP/assert/assert_generror.xml new file mode 100755 index 000000000..2956f3ff7 --- /dev/null +++ b/modules/development_tools/help/ja_JP/assert/assert_generror.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin + * + * 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.1-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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_generror" xml:lang="ja"> + <refnamediv> + <refname>assert_generror</refname> + <refpurpose>エラーを生成する.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + assert_generror ( errormsg ) + assert_generror ( errormsg , errornb ) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>パラメータ</title> + <variablelist> + <varlistentry> + <term>expectedmsg :</term> + <listitem> + <para> + 1行1列の文字列行列, 出力するエラーメッセージ + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>expectederrnb :</term> + <listitem> + <para> + 1行1列のdouble行列,整数値,エラー番号 + (デフォルト: expectederrnb=[]). + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + 指定した引数でエラー関数をコールします. + </para> + <para> + この関数は,予測された出力と計算された出力が一致しない + エラーが発生する度にassert_check* 関数によりコールされます. + assert_check* 関数に指定された + 入力引数の数,出力引数の数,入力引数の型, + または入力引数の内容が間違っている場合, + 通常のエラー関数がコールされます. + この関数はassert_check* 関数の動作を修正するために + カスタマイズできます. + </para> + <para> + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +// 以下のコールは共にエラーを発生します +assert_generror ( "oups" ); +assert_generror ( "oups" , 123456789 ); +// 以下のコールはエラーを発生します +assert_checktrue ( [%t %f] ); +// +// エラーハンドラを定義します +function myerror ( varargin ) + [lhs,rhs]=argn() + errormsg = varargin(1) + if ( rhs == 1 ) then + mprintf( "myerror: %s\n", errormsg ) + else + errornb = varargin(2) + mprintf( "myerror: %s (%d)\n", errormsg , errornb ) + end +endfunction +// +// 新しいエラーハンドラを設定 +back=funcprot(); +funcprot(0); +olderrorfunction = assert_generror; +assert_generror = myerror; +funcprot(back); +// +// 新しいエラーハンドラが設定されたことを確認 +assert_checktrue ( [%t %f] ); +// +// 通常のエラーハンドラに戻します +back=funcprot(); +funcprot(0); +assert_generror = olderrorfunction; +funcprot(back); + ]]></programlisting> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>関数が導入されました + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/bench_run.xml b/modules/development_tools/help/ja_JP/bench_run.xml new file mode 100755 index 000000000..c84e10b52 --- /dev/null +++ b/modules/development_tools/help/ja_JP/bench_run.xml @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 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.1-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" xmlns:scilab="http://www.scilab.org" xml:id="bench_run" xml:lang="ja"> + <refnamediv> + <refname>bench_run</refname> + <refpurpose>ベンチマークテストを実行</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + bench_run() + bench_run(module[,test_name[,options]]) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>引数</title> + <variablelist> + <varlistentry> + <term>module</term> + <listitem> + <para>文字列ベクトル. モジュール名またはツールボックスの絶対パスを指定します.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>test_name</term> + <listitem> + <para>文字列ベクトル</para> + </listitem> + </varlistentry> + <varlistentry> + <term>options</term> + <listitem> + <para>文字列ベクトル</para> + <itemizedlist> + <listitem> + <para>list : モジュールで利用可能なベンチマークテストのリスト</para> + </listitem> + <listitem> + <para>help : Scilabコンソールにいくつかの使用例を表示</para> + </listitem> + <listitem> + <para>nb_run=value : ベンチマークテストを指定回数反復実行</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + ベンチマークテストライブラリの .tst ファイルを探して実行し,実行時間に関する + レポートを表示します. + .tst ファイルはSCI+"/modules/*/tests/benchmark"ディレクトリで探されます. + </para> + <para> + テスト処理を制御しやすくするために,.tstファイルに特殊なタグを挿入できます. + これらのタグはScilabコメントとして記入します. + </para> + <para>利用可能なタグを以下に示します :</para> + <itemizedlist> + <listitem> + <para> + <-- BENCH NB RUN : 10 --> + このテストは10回反復実行されます. + </para> + </listitem> + <listitem> + <para> + <-- BENCH START --> + <-- BENCH END --> + ベンチマークの関心がある部分をこれらのタグで括りますThe + </para> + </listitem> + </itemizedlist> + </refsection> + <refsection> + <title>例</title> + <para>bench_runを実行例をいくつか示します</para> + <programlisting role="example"><![CDATA[ +// 全てのテストを実行 +bench_run(); +bench_run([]); +bench_run([],[]); +// 1つまたは複数のモジュールをテスト +bench_run('core'); +bench_run('core',[]); +bench_run(['core','string']); +// 指定したモジュールの1つまたは複数のテストを実行 +bench_run('core',['trycatch','opcode']); +// オプションを指定 +bench_run([],[],'list'); +bench_run([],[],'help'); +bench_run([],[],'nb_run=2000'); + ]]></programlisting> + <para>ベンチマークファイルの例. このファイルはファイル + SCI/modules/linear_algebra/tests/benchmarks/bench_chol.tstに対応します. + </para> + <programlisting role="example"><![CDATA[ +// ============================================================================= +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2007-2008 - INRIA +// +// This file is distributed under the same license as the Scilab package. +// ============================================================================= +//============================================================================== +// Benchmark for chol function +//============================================================================== +// <-- BENCH NB RUN : 10 --> +stacksize(30000000); +a = 0; +b = 0; +a = rand(900, 900, 'n'); +a = a'*a; +// <-- BENCH START --> +b = chol(a); +// <-- BENCH END --> + ]]></programlisting> + <para>テストの結果</para> + <programlisting role="example"><![CDATA[ +-->bench_run('linear_algebra','bench_chol') + For Loop (as reference) ........................... 143.00 ms [ 1000000 x] + 001/001 - [linear_algebra] bench_chol ...................... 130.60 ms [ 10 x] + ]]></programlisting> + </refsection> + <refsection role="see also"> + <title>参照</title> + <simplelist type="inline"> + <member> + <link linkend="test_run">test_run</link> + </member> + </simplelist> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/example_run.xml b/modules/development_tools/help/ja_JP/example_run.xml new file mode 100755 index 000000000..63e4fbf87 --- /dev/null +++ b/modules/development_tools/help/ja_JP/example_run.xml @@ -0,0 +1,109 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2012 - Scilab Enterprises - Vincent COUVERT + * + * 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.1-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" xmlns:scilab="http://www.scilab.org" xml:id="example_run" xml:lang="ja"> + <refnamediv> + <refname>example_run</refname> + <refpurpose>ヘルプページで見つかった例を実行.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + example_run() + example_run(moduleNames) + example_run(moduleNames, functionNames) + example_run(moduleNames, functionNames, language) + example_run(moduleNames, functionNames, language, testrunOptions, testrunExportToFile) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>引数</title> + <variablelist> + <varlistentry> + <term>moduleNames</term> + <listitem> + <para> + 文字列または文字列ベクトル: テストを行うモジュールの名前. + デフォルト値は + <link linkend="getmodules">getmodules()</link>で返された値です. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>functionNames</term> + <listitem> + <para>文字列または文字列ベクトル: + テストする関数の名前. 指定されないアバイ, + モジュールの全てのヘルプページがテストされます. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>language</term> + <listitem> + <para>文字列: テストするヘルプページの言語. デフォルト値は "en_US"です.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>testrunOptions</term> + <listitem> + <para> + <link linkend="test_run">test_run</link>の第3引数として使用. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>testrunExportToFile</term> + <listitem> + <para> + <link linkend="test_run">test_run</link>の第4引数として使用. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + この巻数は,ヘルプページで指定した例を展開し, + <link linkend="test_run">test_run</link>により実行します. + </para> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +if ~isempty(ls("SCI/modules/xml/help/en_US/*.xml")) then // この例のXMLソースが存在する必要があります + example_run("xml") + example_run("core", "insertion") + example_run("core", ["insertion"; "extraction"]) + example_run("core", "insertion", "en_US") +end + ]]></programlisting> + </refsection> + <refsection role="see also"> + <title>参照</title> + <simplelist type="inline"> + <member> + <link linkend="test_run">test_run</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark>関数example_runが導入されました.</revremark> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/test_run.xml b/modules/development_tools/help/ja_JP/test_run.xml new file mode 100755 index 000000000..28da4d479 --- /dev/null +++ b/modules/development_tools/help/ja_JP/test_run.xml @@ -0,0 +1,490 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) INRIA + * Copyright (C) 2009-2011 - DIGITEO - Michael Baudin + * + * 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.1-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" xmlns:scilab="http://www.scilab.org" xml:id="test_run" xml:lang="ja"> + <refnamediv> + <refname>test_run</refname> + <refpurpose>テストを実行</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + status = test_run() + status = test_run(module) + status = test_run(module, test_name) + status = test_run(module, test_name, options, exportToFile) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>引数</title> + <variablelist> + <varlistentry> + <term>module</term> + <listitem> + <para>文字列の配列. この入力引数には以下のどれかを指定します</para> + <itemizedlist> + <listitem> + <para> + Scilab内部モジュール名 ("core", "time", ...)またはサブモジュール名 (例: "optimization|neldermead"). + </para> + </listitem> + <listitem> + <para> + ATOMSモジュールの名前("module_lycee", "nisp", ...). + 処理を行うには,このモジュールはtest_run()をコールする前に + ロードしておく必要があります. + </para> + </listitem> + <listitem> + <para> + モジュールの絶対ディレクトリパス. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>test_name</term> + <listitem> + <para>文字列配列</para> + </listitem> + </varlistentry> + <varlistentry> + <term>options</term> + <listitem> + <para>文字列配列</para> + <variablelist> + <varlistentry> + <term>no_check_ref</term> + <listitem> + <para>the .dia と .dia.ref が等しい場合, チェックを行いません</para> + </listitem> + </varlistentry> + <varlistentry> + <term>no_check_error_output</term> + <listitem> + <para>エラー出力ストリームはチェックされません. + Scilabがローカライズされたものが利用できないとエラーを発生する + 場合,このオプションを利用できます. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>create_ref</term> + <listitem> + <para>.dia.refファイルを作成し, + .dia と .dia.refが等しいかどうかをチェックしません. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>show_error</term> + <listitem> + <para>エラーが発生した場合直近の10行分の実行行を表示します + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>show_diff</term> + <listitem> + <para> + 差異がみつかった場合,<literal>diff -u</literal>コマンドの結果を + 表示します. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>list</term> + <listitem> + <para> + テストを実行しませんが, + 利用可能なテストの一覧を表示します + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>help</term> + <listitem> + <para> + このコマンドの使用方法に関するいくつかの例を表示します + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>mode_nw</term> + <listitem> + <para>実行時に "-nw" オプションを追加します</para> + </listitem> + </varlistentry> + <varlistentry> + <term>mode_nwni</term> + <listitem> + <para>実行時に "-nwni"オプションを追加します</para> + </listitem> + </varlistentry> + <varlistentry> + <term>nonreg_tests</term> + <listitem> + <para>回帰的でないテストのみを実行し, + ユニットテストをスキップします + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>unit_tests</term> + <listitem> + <para> + ユニットテストのみを実行し,回帰的でないテストをスキップします + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>skip_tests</term> + <listitem> + <para>テストをスキップします</para> + </listitem> + </varlistentry> + <varlistentry> + <term>enable_lt</term> + <listitem> + <para>テストの長時間実行を許可します</para> + </listitem> + </varlistentry> + <varlistentry> + <term>short_summary</term> + <listitem> + <para> + 実行後に統計または実行時間を表示しません + (実行回数,成功/失敗/スキップしたテストの回数のみを1行に表示します). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term>exportToFile</term> + <listitem> + <para> + テストの結果をXMLファイルにエクスポートします. + このファイルはXUnit形式となります. + このオプションの使用により, + <literal>show_diff</literal> および <literal>show_error</literal> + が有効となることに注意してください. + </para> + <para> + <varname>exportToFile</varname>で指定したファイルが既に存在する場合, + 新規結果は既存のファイルに追加されます. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>status</term> + <listitem> + <para> + 論理値で,エラーが検出されなかった場合に %t, + エラーが検出された場合に %f を返します. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + ユニットテストおよび非回帰テストライブラリで + .tstファイルを探して実行し,成功/失敗に関するレポートを表示します. + .tst ファイルはディレクトリ SCI+"/modules/*/tests/unit_tests" + およびSCI+"/modules/*/tests/nonreg_tests"で探されます. + テストが実行される度に, .diaファイルが生成され, + 実行された全コマンドとコンソールに表示されたメッセージのリストが + 出力されます. + スクリプトが実行された後, この.dia ファイルは, + .tst ファイルと同じディレクトリに置かれた.dia.refファイルで + と比較されます. + 2つのファイルが異なる場合,そのテストは失敗となります. + </para> + <para> + テストの処理を制御できるように.tstファイルに特殊なタグを挿入できます. + これらのタグはScilabコメントとして記述します. + </para> + <para>以下に利用可能なタグを示します:</para> + <itemizedlist> + <listitem> + <para> + <-- INTERACTIVE TEST --> + このテストは対話的なものであるため,スキップされます. + </para> + </listitem> + <listitem> + <para> + <-- LONG TIME EXECUTION --> + このテストは長い時間を要するためスキップされます. + このテストを有効にするには,以下のオプションを指定してtest_runを + コールします: "enable_lt" + </para> + </listitem> + <listitem> + <para> + <-- NOT FIXED --> + このテストは,既知ではあるが,未修正のバグであるため,スキップされます. + </para> + </listitem> + <listitem> + <para> + <-- TEST WITH GRAPHIC --> + このテストはオプション "mode_nwni" が使用された場合は実行されません. + </para> + </listitem> + <listitem> + <para> + <-- NO TRY CATCH --> + </para> + </listitem> + <listitem> + <para> + <-- NO CHECK ERROR OUTPUT --> + エラー出力ファイルはチェックされません + </para> + </listitem> + <listitem> + <para> + <-- NO CHECK REF --> + .dia および.dia.refファイルの比較が行われません. + </para> + </listitem> + <listitem> + <para> + <-- ENGLISH IMPOSED --> + このテストは-l en_USオプションを指定した場合のみ実行されます. + </para> + </listitem> + <listitem> + <para> + <-- FRENCH IMPOSED --> + このテストは-l fr_FRオプションを指定した場合のみ実行されます. + </para> + </listitem> + <listitem> + <para> + <-- CLI SHELL MODE --> + (was: <-- JVM NOT MANDATORY -->) + このテストはデフォルトでscilab-cli (nwniモード)でのみ実行されます. + </para> + </listitem> + <listitem> + <para> + <-- WINDOWS ONLY --> + オペレーティング・システムがWindowsでない場合, このテストはスキップされます. + </para> + </listitem> + <listitem> + <para> + <-- UNIX ONLY --> + オペレーティング・システムがUnix OSでない場合, このテストはスキップされます. + </para> + </listitem> + <listitem> + <para> + <-- LINUX ONLY --> + オペレーティング・システムがGNU/Linuxでない場合, このテストはスキップされます. + </para> + </listitem> + <listitem> + <para> + <-- MACOSX ONLY --> + オペレーティング・システムがMac OS Xでない場合, このテストはスキップされます. + </para> + </listitem> + <listitem> + <para> + <-- XCOS TEST --> + このテストは全ての必要なXcosライブラリを実行します. + このテストはnwモードで実行されます. + </para> + </listitem> + </itemizedlist> + <para> + 各テストは"host"コマンドで生成された別のプロセスで実行されます. + これにより,テストにより不安定な環境となる場合でも, + カレントのコマンドの実行を継続できます. + また,テストは他のテストと独立して実行可能となります. + </para> + </refsection> + <refsection> + <title>プラットフォーム毎のテスト</title> + <para> + テストの出力が実行されるプラットフォームに依存している場合があります. + この場合,<literal>.ref</literal>を全てのプラットフォーム用で同じとならず, + いくつかのプラットフォームではユニットテストが失敗する可能性があります. + この場合, + デフォルトの<literal>.ref</literal>と共に + 各プラットフォーム用の<literal>.ref</literal>を作成することができます. + </para> + <para> + プラットフォーム毎の <literal>.ref</literal>には以下のような拡張子の + どれかを付ける必要があります. + </para> + <itemizedlist> + <listitem> + <para> + <literal>.unix.dia.ref</literal>はUnixプラットフォーム用, + </para> + </listitem> + <listitem> + <para> + <literal>.linux.dia.ref</literal>はGNU/Linuxプラットフォーム用, + </para> + </listitem> + <listitem> + <para> + <literal>.win.dia.ref</literal>はWindowsプラットフォーム用, + </para> + </listitem> + <listitem> + <para> + <literal>.macosx.dia.ref</literal>はMac OS Xプラットフォーム用. + </para> + </listitem> + </itemizedlist> + <para> + アルゴリズムは以下のようになります. + まず, <literal>.ref</literal> が探されます. + このファイルが存在しない場合, + 現在のプラットフォームに応じた以下の + プラットフォーム毎の<literal>.ref</literal>ファイルが実行されます. + </para> + <itemizedlist> + <listitem> + <para> + Windowsプラットフォームの場合: <literal>.win.dia.ref</literal>, + </para> + </listitem> + <listitem> + <para> + Max OS X プラットフォームの場合: <literal>.unix.dia.ref</literal>, <literal>.macosx.dia.ref</literal>, + </para> + </listitem> + <listitem> + <para> + GNU/Linuxプラットフォームの場合: <literal>.unix.dia.ref</literal>, <literal>.linux.dia.ref</literal>. + </para> + </listitem> + </itemizedlist> + </refsection> + <refsection> + <title>例</title> + <programlisting role="example"><![CDATA[ +// 全てのテストを実行 +// ============================================= +test_run(); +test_run([]); +test_run([],[]); +// 1つまたは複数のモジュールをテスト +// ============================================= +// 1つのモジュールをテスト +test_run('time'); +// 複数のモジュールをテスト +test_run(['time','string']); +// サブモジュールをテスト +test_run('optimization|neldermead'); +// パスで指定したモジュールを参照 +test_run(SCI+'/modules/core'); +// 指定したテストを実行 +// ============================================= +// テストを1つ指定 +test_run('time','datenum'); +// 複数のテストを指定 +test_run('time',['datenum';'calendar']); +// いくつかのテストをスキップ +// ============================================= +test_run('time',['datenum';'calendar'],'skip_tests'); +// オプション +// ============================================= +// .dia と .dia.ref が等しいかどうかをチェックしません +test_run('time','datenum','no_check_ref'); +// .dia.refファイルを作成しますが,.diaと.dia.refが等しいかどうかをチェックしません +test_run([],[],'create_ref'); +// テストを実行しないが,利用可能なテストの一覧を表示します +test_run([],[],'list'); +// このコマンドの使用法に関するいくつかの例を表示します +test_run([],[],'help'); +// 非回帰テストのみを実行し,ユニットテストをスキップします +test_run([],[],'nonreg_test'); +// ユニットテストのみを実行し,非回帰テストをスキップします +test_run([],[],'unit_test'); +// エラー出力 (std err)をチェックしません +test_run('boolean','bug_2799','no_check_error_output'); +// 複数のオプションを同時に指定 +test_run([],[],['no_check_ref','mode_nw']); + ]]></programlisting> + <programlisting role="example"><![CDATA[ +// (パスで指定した)外部モジュールのユニットテストを実行 +test_run('SCI/contrib/toolbox_skeleton') + ]]></programlisting> + <programlisting role="example"><![CDATA[ +// XML Xunitファイルにエクスポート +test_run('boolean',[],[],TMPDIR+"/boolean_test_run.xml"); +test_run('time','datenum',[],TMPDIR+"/time_datenum_test_run.xml"); + ]]></programlisting> + </refsection> + <refsection> + <title>内部設計</title> + <para> + テストは, + テストファイルが置かれたディレクトリではなく, + テンポラリディレクトリで実行されます. + .tstファイルはテンポラリディレクトリにコピーされた後, + テストが実行され,.dia.ref が元の位置にコピーされます. + </para> + <para> + .tstスクリプトはそのまま実行されません. + かわりに,テンポラリディレクトリにコピーされる際に + ヘッダとフッタが.tstの先頭と終端に挿入されます. + この修正の理由は,出力メッセージを.diaファイルにリダイレクトし, + テストが実行された後に,ユーザがログファイルを取得できるように + するためです. + </para> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revdescription>test_runは以下のステータスを返します: + <itemizedlist><listitem> + エラーが検出されなかった場合に %t を返します + </listitem> + <listitem> + エラーが検出された場合に %f を返します + </listitem> + </itemizedlist> + <para> + <literal>show_diff</literal> および <literal>show_error</literal> が + 新しいオプションとして追加されました + </para> + <para> + <literal>CLI SHELL MODE</literal> タグが追加されました. + <literal>JVM NOT MANDATORY</literal> (まだサポート中)を置き換えます + </para> + <para> + <literal>test_run</literal> は外部モジュールでも動作します. + </para> + <para> + XMLファイルにエクスポートする4番目の引数が追加されました + </para> + </revdescription> + </revision> + </revhistory> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ja_JP/user.xml b/modules/development_tools/help/ja_JP/user.xml new file mode 100755 index 000000000..c082ee6a5 --- /dev/null +++ b/modules/development_tools/help/ja_JP/user.xml @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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="ja" xml:id="user"> + <refnamediv> + <refname>user</refname> + <refpurpose>Fortran または C ルーチンとのインターフェイスを作成</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼出し手順</title> + <synopsis>[s_1,s_2,...,s_lhs]=user(e_1,e_2,...,e_rhs)</synopsis> + </refsynopsisdiv> + <refsection> + <title>説明</title> + <para> + このコマンドにより,Scilabコマンドとして外部プログラムを使用できるように + なります. + ただし,<literal>(s_1,s_2,...,s_lhs)</literal>は出力変数であり, + <literal>(e_1,e_2,...,e_rhs)</literal>は入力変数です. + このコマンドをScilabに挿入するには,ScilabのFortranサブルーチン + <literal>user</literal>に数行を追加する必要があります. + 詳細については,<link linkend="intersci">intersci</link>またはScilabのドキュメントを参照ください. + </para> + </refsection> + <refsection role="see also"> + <title>参照</title> + <simplelist type="inline"> + <member> + <link linkend="fort">fort</link> + </member> + <member> + <link linkend="link">link</link> + </member> + <member> + <link linkend="intersci">intersci</link> + </member> + </simplelist> + </refsection> +</refentry> diff --git a/modules/development_tools/help/pt_BR/addchapter.sce b/modules/development_tools/help/pt_BR/addchapter.sce new file mode 100755 index 000000000..3540b1b81 --- /dev/null +++ b/modules/development_tools/help/pt_BR/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// 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.1-en.txt + +add_help_chapter("Ferramentas de Desenvolvimento",SCI+"/modules/development_tools/help/pt_BR",%T); + diff --git a/modules/development_tools/help/pt_BR/user.xml b/modules/development_tools/help/pt_BR/user.xml new file mode 100755 index 000000000..528b0b986 --- /dev/null +++ b/modules/development_tools/help/pt_BR/user.xml @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="user" xml:lang="pt"> + <refnamediv> + <refname>user</refname> + <refpurpose>interface para rotinas FORTRAN ou C</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Seqncia de Chamamento</title> + <synopsis>[s_1,s_2,...,s_lhs]=user(e_1,e_2,...,e_rhs)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Descrio</title> + <para>Com este comando, possvel utilizar um programa externo como um + comando do Scilab onde <literal>(s_1,s_2,...,s_lhs)</literal> so as + variveis de sada e<literal> (e_1,e_2,...,e_rhs)</literal> aso as + variveis de entrada. Para inserir este comando no Scilab, necessrio + escrever algumas linhas na subrotina FORTRAN <literal>user</literal> do + Scilab. Ver <link linkend="intersci">intersci</link> ou a documentao do Scilab para + mais . + </para> + </refsection> + <refsection> + <title> Ver Tambm </title> + <simplelist type="inline"> + <member> + <link linkend="fort">fort</link> + </member> + <member> + <link linkend="link">link</link> + </member> + <member> + <link linkend="intersci">intersci</link> + </member> + </simplelist> + </refsection> +</refentry> diff --git a/modules/development_tools/help/ru_RU/addchapter.sce b/modules/development_tools/help/ru_RU/addchapter.sce new file mode 100755 index 000000000..6f8b4e5a1 --- /dev/null +++ b/modules/development_tools/help/ru_RU/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// 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.1-en.txt + +add_help_chapter("Development tools",SCI+"/modules/development_tools/help/ru_RU",%T); + diff --git a/modules/development_tools/help/ru_RU/user.xml b/modules/development_tools/help/ru_RU/user.xml new file mode 100755 index 000000000..8edc73037 --- /dev/null +++ b/modules/development_tools/help/ru_RU/user.xml @@ -0,0 +1,35 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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="ru" xml:id="user"> + <refnamediv> + <refname>user</refname> + <refpurpose>установка связи с подпрограммами Fortran или C</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Последовательность вызова</title> + <synopsis>[s_1,s_2,...,s_lhs]=user(e_1,e_2,...,e_rhs)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Описание</title> + <para> + С этой командой можно использовать внешнюю программу как команду Scilab'а, где + <literal>(s_1,s_2,...,s_lhs)</literal> -- выходные переменные, а + <literal>(e_1,e_2,...,e_rhs)</literal> -- входные переменные. Чтобы ввести эту + команду в Scilab, нужно написать несколько строк в fortran-подпрограмме + <literal>user</literal> Scilab'а. См. <link linkend="intersci">intersci</link> или документацию по Scilab'у для дополнительной информации. + </para> + </refsection> + <refsection role="see also"> + <title>Смотрите также</title> + <simplelist type="inline"> + <member> + <link linkend="fort">fort</link> + </member> + <member> + <link linkend="link">link</link> + </member> + <member> + <link linkend="intersci">intersci</link> + </member> + </simplelist> + </refsection> +</refentry> |