Bug #12550 : the Optimbase help page did not respect Scilab help format. 25/11325/6
Adeline CARNIS [Thu, 18 Apr 2013 15:58:50 +0000 (17:58 +0200)]
Change-Id: I2f3095e3bc6253645a7dcb584da01ffea481b29e

27 files changed:
scilab/modules/optimization/help/en_US/optimbase/optimbase.xml [deleted file]
scilab/modules/optimization/help/en_US/optimbase/optimbase_cget.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_checkbounds.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_checkcostfun.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_checkx0.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_configure.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_destroy.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_function.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_get.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_hasbounds.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_hasconstraints.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_hasnlcons.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_histget.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_histset.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_incriter.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_isfeasible.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_isinbounds.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_isinnonlincons.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_log.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_new.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_outputcmd.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_outstruct.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_overview.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_proj2bnds.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_set.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_stoplog.xml [new file with mode: 0644]
scilab/modules/optimization/help/en_US/optimbase/optimbase_terminate.xml [new file with mode: 0644]

diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase.xml
deleted file mode 100644 (file)
index dab8c30..0000000
+++ /dev/null
@@ -1,1612 +0,0 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2008-2009 - INRIA - Michael Baudin
- * 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-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: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="optimbase" xml:lang="fr">
-    <refnamediv>
-        <refname>optimbase</refname>
-        <refpurpose>Provides an abstract class for a general optimization
-            component.
-        </refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>SYNOPSIS</title>
-        <synopsis>
-            newobj = optimbase_new ()
-            this = optimbase_destroy (this)
-            this = optimbase_configure (this,key,value)
-            value = optimbase_cget (this,key)
-            value = optimbase_get (this,key)
-            this = optimbase_set ( this , key , value )
-            this = optimbase_checkbounds ( this )
-            this = optimbase_checkx0 ( this )
-            [ this , f , index [ , data ] ] = optimbase_function ( this , x , index [ , data ] )
-            [ this , f , c , index [ , data ] ] = optimbase_function ( this , x , index [ , data ] )
-            [ this , f , g , index [ , data ] ] = optimbase_function ( this , x , index [ , data ] )
-            [ this , f , g , c , gc , index [ , data ] ] = optimbase_function ( this , x , index [ , data ] )
-            [ this , hasbounds ] = optimbase_hasbounds ( this )
-            [ this , hascons ] = optimbase_hasconstraints ( this )
-            [ this , hasnlcons ] = optimbase_hasnlcons ( this )
-            value = optimbase_histget ( this , iter , key )
-            this = optimbase_histset ( this , iter , key , value )
-            this = optimbase_incriter ( this )
-            [ this , isfeasible ] = optimbase_isfeasible ( this , x )
-            this = optimbase_log (this,msg)
-            stop = optimbase_outputcmd ( this , state , data )
-            data = optimbase_outstruct ( this )
-            [ this , p ] = optimbase_proj2bnds ( this ,  x )
-            this = optimbase_stoplog ( this , msg )
-            [this , terminate , status] = optimbase_terminate (this , previousfopt , currentfopt , previousxopt , currentxopt )
-            this = optimbase_checkcostfun ( this )
-            [ this , isfeasible ] = optimbase_isinbounds ( this , x )
-            [ this , isfeasible ] = optimbase_isinnonlinconst ( this , x )
-        </synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Purpose</title>
-        <para>The goal of this component is to provide a building block for
-            optimization methods. The goal is to provide a building block for a large
-            class of specialized optimization methods. This component manages
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>the number of variables,</para>
-            </listitem>
-            <listitem>
-                <para>the minimum and maximum bounds,</para>
-            </listitem>
-            <listitem>
-                <para>the number of non linear inequality constraints,</para>
-            </listitem>
-            <listitem>
-                <para>the cost function,</para>
-            </listitem>
-            <listitem>
-                <para>the logging system,</para>
-            </listitem>
-            <listitem>
-                <para>various termination criteria,</para>
-            </listitem>
-            <listitem>
-                <para>etc...</para>
-            </listitem>
-        </itemizedlist>
-        <para>This toolbox is designed with Oriented Object ideas in mind.</para>
-    </refsection>
-    <refsection>
-        <title>Features</title>
-        <para>The following is a list of features the Optimbase toolbox currently
-            provides :
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>Manage cost function</para>
-                <itemizedlist>
-                    <listitem>
-                        <para>optionnal additionnal argument</para>
-                    </listitem>
-                    <listitem>
-                        <para>direct communication of the task to perform : cost function
-                            or inequality constraints
-                        </para>
-                    </listitem>
-                </itemizedlist>
-            </listitem>
-            <listitem>
-                <para>Manage various termination criteria, including</para>
-                <itemizedlist>
-                    <listitem>
-                        <para>maximum number of iterations,</para>
-                    </listitem>
-                    <listitem>
-                        <para>tolerance on function value (relative or absolute),</para>
-                    </listitem>
-                    <listitem>
-                        <para>tolerance on x (relative or absolute),</para>
-                    </listitem>
-                    <listitem>
-                        <para>maximum number of evaluations of cost function,</para>
-                    </listitem>
-                </itemizedlist>
-            </listitem>
-            <listitem>
-                <para>Manage the history of the convergence, including</para>
-                <itemizedlist>
-                    <listitem>
-                        <para>history of function values,</para>
-                    </listitem>
-                    <listitem>
-                        <para>history of optimum point.</para>
-                    </listitem>
-                </itemizedlist>
-            </listitem>
-            <listitem>
-                <para>Provide query features for</para>
-                <itemizedlist>
-                    <listitem>
-                        <para>the status of the optimization process,</para>
-                    </listitem>
-                    <listitem>
-                        <para>the number of iterations,</para>
-                    </listitem>
-                    <listitem>
-                        <para>the number of function evaluations,</para>
-                    </listitem>
-                    <listitem>
-                        <para>function value at initial point,</para>
-                    </listitem>
-                    <listitem>
-                        <para>function value at optimal point,</para>
-                    </listitem>
-                    <listitem>
-                        <para>the optimum parameters,</para>
-                    </listitem>
-                    <listitem>
-                        <para>etc...</para>
-                    </listitem>
-                </itemizedlist>
-            </listitem>
-        </itemizedlist>
-    </refsection>
-    <refsection>
-        <title>Description</title>
-        <para>This set of commands allows to manage an abstract optimization
-            method. The goal is to provide a building block for a large class of
-            specialized optimization methods. This component manages the number of
-            variables, the minimum and maximum bounds, the number of non linear
-            inequality constraints, the logging system, various termination criteria,
-            the cost function, etc...
-        </para>
-        <para>The optimization problem to solve is the following</para>
-        <programlisting role="example">
-            min f(x)
-            l_i &lt;= x_i &lt;= h_i, i = 1,n
-            g_i(x) &gt;= 0, i = 1,nbineq
-        </programlisting>
-        <para>where</para>
-        <variablelist>
-            <varlistentry>
-                <term>n</term>
-                <listitem>
-                    <para>number of variables</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>nbineq</term>
-                <listitem>
-                    <para>number of inequality constraints</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Functions</title>
-        <para>The following functions are available.</para>
-        <variablelist>
-            <varlistentry>
-                <term xml:id="optimbase_new">newobj = optimbase_new ()</term>
-                <listitem>
-                    <para>Creates a new optimization object.</para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>newobj</term>
-                            <listitem>
-                                <para>The new object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_destroy">this = optimbase_destroy
-                    (this)
-                </term>
-                <listitem>
-                    <para>Destroy the given object.</para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_configure">this = optimbase_configure
-                    (this,key,value)
-                </term>
-                <listitem>
-                    <para>Configure the current object with the given value for the
-                        given key.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>key</term>
-                            <listitem>
-                                <para>the key to configure. The following keys are
-                                    available.
-                                </para>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>-verbose</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, integer
-                                                value, set to 1 to enable verbose logging (default
-                                                verbose = 0).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-verbosetermination</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, integer
-                                                value, set to 1 to enable verbose termination logging
-                                                (default verbosetermination = 0).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-x0</term>
-                                        <listitem>
-                                            <para>a n-by-1 matrix of doubles, where n is the number
-                                                of variables, the initial guess.
-                                            </para>
-                                            <para>There is no default value, i.e. the user must
-                                                provide <literal>x0</literal>.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-maxfunevals</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, integer
-                                                value, the maximum number of function evaluations
-                                                (default maxfunevals = 100). If this criteria is
-                                                triggered, the status of the optimization is set to
-                                                "maxfuneval".
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-maxiter</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, integer
-                                                value, the maximum number of iterations (default maxiter
-                                                = 100). If this criteria is triggered, the status of the
-                                                optimization is set to "maxiter".
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-tolfunabsolute</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, the absolute
-                                                tolerance for the function value (default tolfunabsolute
-                                                = 0).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-tolfunrelative</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, the relative
-                                                tolerance for the function value (default tolfunrelative
-                                                = %eps).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-tolfunmethod</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of booleans, set to %t to enable
-                                                termination with tolerance on function value (default
-                                                tolfunmethod = %f).
-                                            </para>
-                                            <para>If this criteria is triggered, the status of the
-                                                optimization is set to "tolf".
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-tolxabsolute</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, the absolute
-                                                tolerance on x (default tolxabsolute = 0).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-tolxrelative</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, the relative
-                                                tolerance on x (default tolxrelative =
-                                                sqrt(%eps)).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-tolxmethod</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of booleans, set to %t to enable
-                                                the tolerance on x in the termination criteria (default
-                                                tolxmethod = %t).
-                                            </para>
-                                            <para>If this criteria is triggered, the status of the
-                                                optimization is set to "tolx".
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-function</term>
-                                        <listitem>
-                                            <para>a function or a list, the objective function. This
-                                                function computes the value of the cost and the non
-                                                linear constraints, if any.
-                                            </para>
-                                            <para>There is no default value, i.e. the user must
-                                                provide <literal>f</literal>.
-                                            </para>
-                                            <para>See below for the details of the communication
-                                                between the optimization system and the cost
-                                                function.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-outputcommand</term>
-                                        <listitem>
-                                            <para>a function or a list, a function which is called
-                                                back for output.
-                                            </para>
-                                            <para>See below for the details of the communication
-                                                between the optimization system and the output command
-                                                function.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-numberofvariables</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, integer
-                                                value, the number of variables to optimize (default
-                                                numberofvariables = 0).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-storehistory</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of booleans, set to %t to enable
-                                                the history storing (default storehistory = %f).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-boundsmin</term>
-                                        <listitem>
-                                            <para>a n-by-1 matrix of doubles, the minimum bounds for
-                                                the parameters where n is the number of variables
-                                                (default boundsmin = [], i.e. there are no minimum
-                                                bounds).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-boundsmax</term>
-                                        <listitem>
-                                            <para>a n-by-1 matrix of doubles, the maximum bounds for
-                                                the parameters where n is the number of variables
-                                                (default boundsmax = [], i.e. there are no maximum
-                                                bounds).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-nbineqconst</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of doubles, positive, integer
-                                                value, the number of inequality constraints (default
-                                                nbineqconst = 0).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-logfile</term>
-                                        <listitem>
-                                            <para>the name of the log file</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-withderivatives</term>
-                                        <listitem>
-                                            <para>a 1-by-1 matrix of booleans, set to %t if the
-                                                algorithm uses derivatives (default withderivatives =
-                                                %f).
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>value</term>
-                            <listitem>
-                                <para>the value.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_cget">value = optimbase_cget (this,key)</term>
-                <listitem>
-                    <para>Get the value for the given key. If the key is unknown,
-                        generates an error.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>key</term>
-                            <listitem>
-                                <para>the name of the key to quiery. The list of available
-                                    keys is the same as for the optimbase_configure
-                                    function.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_checkbounds">this = optimbase_checkbounds (
-                    this )
-                </term>
-                <listitem>
-                    <para>Check if the bounds are consistent and produces an error
-                        message if not.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_checkx0">opt = optimbase_checkx0 ( this
-                    )
-                </term>
-                <listitem>
-                    <para>Check if the initial guess is consistent with the bounds and
-                        the non linear inequality constraints, if any and produces an error
-                        message if not.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_function">optimbase_function</term>
-                <listitem>
-                    <para>Call the cost function and return the required results.</para>
-                    <para>If a cost function additionnal argument is defined in current
-                        object, pass it to the function as the last argument.
-                    </para>
-                    <para>The following calling sequences are available (see below for
-                        more details).
-                    </para>
-                    <programlisting role="example">
-                        [ this , f , index ] = optimbase_function ( this , x , index )
-                        [ this , f , c , index ] = optimbase_function ( this , x , index )
-                        [ this , f , g , index ] = optimbase_function ( this , x , index )
-                        [ this , f , g , c , gc , index ] = optimbase_function ( this , x , index )
-                    </programlisting>
-                    <para/>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>x</term>
-                            <listitem>
-                                <para>the current point, as a column vector</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>index</term>
-                            <listitem>
-                                <para>what value to compute.</para>
-                                <para>See below in the section "Cost function" for details on
-                                    this index.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>f</term>
-                            <listitem>
-                                <para>the value of the cost function</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>g</term>
-                            <listitem>
-                                <para>the gradient of the cost function</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>c</term>
-                            <listitem>
-                                <para>the nonlinear, positive, inequality constraints</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>gc</term>
-                            <listitem>
-                                <para>the gradient of the nonlinear, positive, inequality
-                                    constraints
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_set">this = optimbase_set ( this , key , value
-                    )
-                </term>
-                <listitem>
-                    <para>Set the value for the given key. If the key is unknown,
-                        generates an error.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>key</term>
-                            <listitem>
-                                <para>the key to set</para>
-                                <para>The following keys are available :</para>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>-funevals</term>
-                                        <listitem>
-                                            <para>the number of function evaluations</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-iterations</term>
-                                        <listitem>
-                                            <para>the number of iterations</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-xopt</term>
-                                        <listitem>
-                                            <para>the x optimum</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-fopt</term>
-                                        <listitem>
-                                            <para>the optimum cost function value</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-historyxopt</term>
-                                        <listitem>
-                                            <para>an array, with nbiter values, containing the
-                                                history of x during the iterations.
-                                            </para>
-                                            <para>This array is available after optimization if the
-                                                history storing was enabled with the -storehistory
-                                                option.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-historyfopt</term>
-                                        <listitem>
-                                            <para>an array, with nbiter values, containing the
-                                                history of the function value during the
-                                                iterations.
-                                            </para>
-                                            <para>This array is available after optimization if the
-                                                history storing was enabled with the -storehistory
-                                                option.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-fx0</term>
-                                        <listitem>
-                                            <para>the function value for the initial guess</para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>-status</term>
-                                        <listitem>
-                                            <para>a string containing the status of the
-                                                optimization
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>value</term>
-                            <listitem>
-                                <para>the value to set</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_get">value = optimbase_get (this,key)</term>
-                <listitem>
-                    <para>Get the value for the given key. If the key is unknown,
-                        generates an error. This command corresponds with options which are
-                        not available directly to the optimbase_configure function, but are
-                        computed internally.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>key</term>
-                            <listitem>
-                                <para>the name of the key to quiery.</para>
-                                <para>The list of available keys is the same as the
-                                    optimbase_set function.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_hasbounds">[ this , hasbounds ] =
-                    optimbase_hasbounds ( this )
-                </term>
-                <listitem>
-                    <para>Returns %T if current problem has bounds.</para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_hasconstraints">[ this , hascons ] =
-                    optimbase_hasconstraints ( this )
-                </term>
-                <listitem>
-                    <para>Returns %T if current problem has bounds constraints, linear
-                        constraints or non linear constraints.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_hasnlcons">[ this , hasnlcons ] =
-                    optimbase_hasnlcons ( this )
-                </term>
-                <listitem>
-                    <para>Returns %T if current problem has non linear
-                        constraints.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_histset">this = optimbase_histset ( this ,
-                    iter , key , value )
-                </term>
-                <listitem>
-                    <para>Set the history value at given iteration for the given key. If
-                        the key is unknown, generates an error.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>iter</term>
-                            <listitem>
-                                <para>the iteration number to get</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>key</term>
-                            <listitem>
-                                <para>the name of the key to quiery.</para>
-                                <para>The list of available keys is the following : "-xopt",
-                                    "-fopt".
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>value</term>
-                            <listitem>
-                                <para>the value to set</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_histget">value = optimbase_histget ( this ,
-                    iter , key )
-                </term>
-                <listitem>
-                    <para>Returns the history value at the given iteration number for
-                        the given key. If the key is unknown, generates an error.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>iter</term>
-                            <listitem>
-                                <para>the iteration number to get</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>key</term>
-                            <listitem>
-                                <para>the name of the key to quiery.</para>
-                                <para>The list of available keys is the same as the
-                                    optimbase_histset function.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_incriter">this = optimbase_incriter ( this
-                    )
-                </term>
-                <listitem>
-                    <para>Increments the number of iterations.</para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_isfeasible">[ this , isfeasible ] =
-                    optimbase_isfeasible ( this , x )
-                </term>
-                <listitem>
-                    <para>Returns 1 if the given point satisfies bounds constraints and
-                        inequality constraints. Returns 0 if the given point is not in the
-                        bounds. Returns -1 if the given point does not satisfies inequality
-                        constraints.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>x</term>
-                            <listitem>
-                                <para>the current point</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_log">this = optimbase_log (this,msg)</term>
-                <listitem>
-                    <para>If verbose logging is enabled, prints the given message in the
-                        console. If verbose logging is disabled, does nothing. If the
-                        -lofgile option has been set, writes the message into the file
-                        instead of writing to the console. If the console is too slow,
-                        writing into a file can be a solution, since it is very fast.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>msg</term>
-                            <listitem>
-                                <para>the message to print</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_outputcmd">stop = optimbase_outputcmd ( this ,
-                    state , data )
-                </term>
-                <listitem>
-                    <para>Calls back user's output command. See below for details, in
-                        the "The output function" section.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>state</term>
-                            <listitem>
-                                <para>a 1-by-1 matrix of strings, the current state of the
-                                    algorithm
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>data</term>
-                            <listitem>
-                                <para>a data structure with type T_OPTDATA. This is typically
-                                    the output of the <literal>optimbase_outstruct</literal>
-                                    function, with potentially additionnal fields.
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_outstruct">data = optimbase_outstruct ( this
-                    )
-                </term>
-                <listitem>
-                    <para>Returns a data structure with type T_OPTDATA. This data
-                        structure contains basic optimization fields. The output argument
-                        <literal>data</literal> is designed to be the input of the
-                        <literal>optimbase_outputcmd</literal> function which, in turn,
-                        calls back the output function. This data structure may be enriched
-                        by children (specialized) optimization methods.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_proj2bnds">[ this , p ] = optimbase_proj2bnds
-                    ( this , x )
-                </term>
-                <listitem>
-                    <para>Returns a point, which is the projection of the given point
-                        into the bounds.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>x</term>
-                            <listitem>
-                                <para>the current point</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_stoplog">this = optimbase_stoplog ( this , msg
-                    )
-                </term>
-                <listitem>
-                    <para>Prints the given stopping rule message if verbose termination
-                        is enabled. If verbose termination is disabled, does nothing.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>msg</term>
-                            <listitem>
-                                <para>the message to print</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_terminate">[this , terminate , status] =
-                    optimbase_terminate (this , previousfopt , currentfopt , previousxopt
-                    , currentxopt )
-                </term>
-                <listitem>
-                    <para>Returns 1 if the algorithm terminates. Returns 0 if the
-                        algorithm must continue. If the -verbosetermination option is
-                        enabled, messages are printed detailing the termination intermediate
-                        steps. The optimbase_terminate function takes into account the
-                        number of iterations, the number of evaluations of the cost
-                        function, the tolerance on x and the tolerance on f. See below in
-                        the section "Termination" for more details.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>previousfopt</term>
-                            <listitem>
-                                <para>the previous value of the cost function</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>currentfopt</term>
-                            <listitem>
-                                <para>the current value of the cost function</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>previousxopt</term>
-                            <listitem>
-                                <para>the previous x optimum</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>currentxopt</term>
-                            <listitem>
-                                <para>the current x optimum</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>terminate</term>
-                            <listitem>
-                                <para>%t if the algorithm must terminate, %f if the algorithm
-                                    must continue
-                                </para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>status</term>
-                            <listitem>
-                                <para>if terminate = %t, the detailed status of the
-                                    termination, as a string. If terminate = %f, the status is
-                                    "continue".
-                                </para>
-                                <para>The following status are available :</para>
-                                <variablelist>
-                                    <varlistentry>
-                                        <term>"maxiter"</term>
-                                        <listitem>
-                                            <para>the maximum number of iterations, provided by the
-                                                -maxiter option, is reached.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>"maxfuneval"</term>
-                                        <listitem>
-                                            <para>the maximum number of function evaluations,
-                                                provided by the -maxfunevals option, is reached
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>"tolf"</term>
-                                        <listitem>
-                                            <para>the tolerance on the function value is reached.
-                                                This status is associated with the -tolfunmethod,
-                                                -tolfunabsolute and -tolfunrelative options.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                    <varlistentry>
-                                        <term>"tolx"</term>
-                                        <listitem>
-                                            <para>the tolerance on x is reached. This status is
-                                                associated with the -tolxmethod, -tolxabsolute and
-                                                -tolxrelative options.
-                                            </para>
-                                        </listitem>
-                                    </varlistentry>
-                                </variablelist>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_checkcostfun">this = optimbase_checkcostfun (
-                    this )
-                </term>
-                <listitem>
-                    <para>Check that the cost function is correctly connected. Generate
-                        an error if there is one. Takes into account for the cost function
-                        at the initial guess x0 only. Checks that all values of the index
-                        argument are valid. If there are nonlinear constraints, check that
-                        the matrix has the correct shape.
-                    </para>
-                    <para>This function requires at least one call to the cost function
-                        to make the necessary checks.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_isinbounds">[ this , isfeasible ] =
-                    optimbase_isinbounds ( this , x )
-                </term>
-                <listitem>
-                    <para>Returns isfeasible = %t if the given point satisfies bounds
-                        constraints. Returns isfeasible = %f if the given point is not in
-                        the bounds.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>isfeasible</term>
-                            <listitem>
-                                <para>a boolean</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term xml:id="optimbase_isinnonlinconst">[ this , isfeasible ] =
-                    optimbase_isinnonlinconst ( this , x )
-                </term>
-                <listitem>
-                    <para>Returns isfeasible = %t if the given point satisfies the
-                        nonlinear constraints. Returns isfeasible = %f if the given point
-                        does not satisfy the nonlinear constraints.
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>this</term>
-                            <listitem>
-                                <para>The current object.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>isfeasible</term>
-                            <listitem>
-                                <para>a boolean</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>The cost function</title>
-        <para>
-            The <literal>-function</literal> option allows to configure the cost
-            function. The cost function is used, depending on the context, to compute
-            the cost, the nonlinear inequality positive constraints, the gradient of
-            the function and the gradient of the nonlinear inequality
-            constraints.
-        </para>
-        <para>The cost function can also be used to produce outputs and to
-            terminate an optimization algorithm.
-        </para>
-        <para>In the following, the variables are</para>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    <literal>f</literal>: scalar, the objective,
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    <literal>g</literal>: row matrix, the gradient of the
-                    objective,
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    <literal>c</literal>: row matrix, the constraints,
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    <literal>gc</literal>: matrix, the gradient of the
-                    constraints.
-                </para>
-            </listitem>
-        </itemizedlist>
-        <para>
-            Each calling sequence of the <literal>optimbase_function</literal>
-            function corresponds to a specific calling sequence of the user-provided
-            cost function.
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>If the -withderivatives is false and there is no nonlinear
-                    constraint, the calling sequence is
-                </para>
-                <programlisting role="example">
-                    
-                    [ this , f , index ] = optimbase_function ( this , x , index )
-                    
-                </programlisting>
-                <para>which corresponds to the cost functions</para>
-                <programlisting role="example">
-                    
-                    [ f , index ] = costf ( x , index ) 
-                    
-                </programlisting>
-            </listitem>
-            <listitem>
-                <para>If the -withderivatives is false and there are nonlinear
-                    constraints, the calling sequence is
-                </para>
-                <programlisting role="example">
-                    
-                    [ this , f , c , index ] = optimbase_function ( this , x , index )
-                    
-                </programlisting>
-                <para>which corresponds to the cost functions</para>
-                <programlisting role="example">
-                    
-                    [ f , c , index ] = costf ( x , index ) 
-                    
-                </programlisting>
-            </listitem>
-            <listitem>
-                <para>If the -withderivatives is true and there is no nonlinear
-                    constraint, the calling sequence is
-                </para>
-                <programlisting role="example">
-                    
-                    [ this , f , g , index ] = optimbase_function ( this , x , index )
-                    
-                </programlisting>
-                <para>which corresponds to the cost functions</para>
-                <programlisting role="example">
-                    
-                    [ f , g , index ] = costf ( x , index ) 
-                    
-                </programlisting>
-            </listitem>
-            <listitem>
-                <para>If the -withderivatives is true and there is are nonlinear
-                    constraints, the calling sequence is
-                </para>
-                <programlisting role="example">
-                    
-                    [ this , f , g , c , gc , index ] = optimbase_function ( this , x , index )
-                    
-                </programlisting>
-                <para>which corresponds to the cost functions</para>
-                <programlisting role="example">
-                    
-                    [ f , g , c , gc , index ] = costf ( x , index ) 
-                    
-                </programlisting>
-            </listitem>
-        </itemizedlist>
-        <para>Each calling sequence corresponds to a particular class of
-            algorithms, including for example
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>unconstrained, derivative-free algorithms,</para>
-            </listitem>
-            <listitem>
-                <para>nonlinearily constrained, derivative-free algorithms,</para>
-            </listitem>
-            <listitem>
-                <para>unconstrained, derivative-based algorithms,</para>
-            </listitem>
-            <listitem>
-                <para>nonlinearilyconstrained, derivative-based algorithms,</para>
-            </listitem>
-            <listitem>
-                <para>etc...</para>
-            </listitem>
-        </itemizedlist>
-        <para>The current component is designed in order to be able to handle many
-            situations.
-        </para>
-        <para>The index input parameter has the following meaning.</para>
-        <itemizedlist>
-            <listitem>
-                <para>index = 1: nothing is to be computed, the user may display
-                    messages, for example
-                </para>
-            </listitem>
-            <listitem>
-                <para>index = 2: compute f</para>
-            </listitem>
-            <listitem>
-                <para>index = 3: compute g</para>
-            </listitem>
-            <listitem>
-                <para>index = 4: compute f and g</para>
-            </listitem>
-            <listitem>
-                <para>index = 5: compute c</para>
-            </listitem>
-            <listitem>
-                <para>index = 6: compute f and c</para>
-            </listitem>
-            <listitem>
-                <para>index = 7: compute f, g, c and gc</para>
-            </listitem>
-        </itemizedlist>
-        <para>The index output parameter has the following meaning.</para>
-        <itemizedlist>
-            <listitem>
-                <para>index &gt; 0: everything is fine,</para>
-            </listitem>
-            <listitem>
-                <para>index = 0: the optimization must stop,</para>
-            </listitem>
-            <listitem>
-                <para>index &lt; 0: one function could not be avaluated.</para>
-            </listitem>
-        </itemizedlist>
-        <para>It might happen that the function requires additionnal arguments to
-            be evaluated. In this case, we can use the following feature. The argument
-            <literal>fun</literal> can also be the list
-            <literal>(f,a1,a2,...)</literal>. In this case <literal>f</literal>, the
-            first element in the list, must be a function and must have the header:
-            <programlisting>
-                [ f , index ] = f ( x , index , a1 , a2 , ... )
-                [ f , c , index ] = f ( x , index , a1 , a2 , ... )
-                [ f , g , index ] = f ( x , index , a1 , a2 , ... )
-                [ f , g , c , gc , index ] = f ( x , index , a1 , a2 , ... )
-            </programlisting>
-            where the input arguments <literal>a1, a2,
-                ...
-            </literal>
-            are automatically appended at the end of the calling
-            sequence.
-        </para>
-    </refsection>
-    <refsection>
-        <title>The output function</title>
-        <para>The option -outputcommand allows to configure a command which is
-            called back at the start of the optimization, at each iteration and at the
-            end of the optimization.
-        </para>
-        <para>The output function must have the following header</para>
-        <programlisting role="example">
-            stop = outputcmd(state, data)
-        </programlisting>
-        <para>where</para>
-        <variablelist>
-            <varlistentry>
-                <term>state</term>
-                <listitem>
-                    <para>a 1-by-1 matrix of strings, the current state of the
-                        algorithm. Available values are "init", "iter", "done".
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>data</term>
-                <listitem>
-                    <para>
-                        a data structure with type <literal>T_OPTDATA</literal>
-                        containing at least the following fields
-                    </para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>x</term>
-                            <listitem>
-                                <para>the current optimum</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>fval</term>
-                            <listitem>
-                                <para>the current function value</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>iteration</term>
-                            <listitem>
-                                <para>the current iteration index</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>funccount</term>
-                            <listitem>
-                                <para>the number of function evaluations</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>stop</term>
-                <listitem>
-                    <para>a 1-by-1 matrix of booleans, stop is true if the optimization
-                        algorithm must be stopped, stop is false if the optimization
-                        algorithm must continue.
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-        <para>It might happen that the output function requires additionnal
-            arguments to be evaluated. In this case, we can use the following feature.
-            The argument <literal>outputcmd</literal> can also be the list
-            <literal>(outf,a1,a2,...)</literal>. In this case <literal>outf</literal>,
-            the first element in the list, must be a function and must have the
-            header: <programlisting>
-                stop = outf ( state, data, a1, a2, ... )
-            </programlisting>
-            where the input arguments <literal>a1, a2,
-                ...
-            </literal>
-            are automatically appended at the end of the calling
-            sequence.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Termination</title>
-        <para>The current component takes into account for several generic
-            termination criterias. Specialized termination criterias should be
-            implemented in specialized optimization algorithms, by calling the
-            optimbase_termination function and adding external criterias, rather than
-            by modification of this function.
-        </para>
-        <para>The optimbase_terminate function uses a set of rules to compute if
-            the termination occurs, which leads to an optimization status which is
-            equal to one of the following : "continue", "maxiter", "maxfunevals",
-            "tolf", "tolx". The set of rules is the following.
-        </para>
-        <itemizedlist>
-            <listitem>
-                <para>By default, the status is "continue" and the terminate flag is
-                    0.
-                </para>
-            </listitem>
-            <listitem>
-                <para>The number of iterations is examined and compared to the
-                    -maxiter option : if the following condition
-                </para>
-                <programlisting role="example">
-                    iterations &gt;= maxiter
-                </programlisting>
-                <para>is true, then the status is set to "maxiter" and terminate is
-                    set to %t.
-                </para>
-            </listitem>
-            <listitem>
-                <para>The number of function evaluations and compared to the
-                    -maxfunevals option is examined : if the following condition
-                </para>
-                <programlisting role="example">
-                    funevals &gt;= maxfunevals
-                </programlisting>
-                <para>is true, then the status is set to "maxfuneval" and terminate is
-                    set to %t.
-                </para>
-            </listitem>
-            <listitem>
-                <para>The tolerance on function value is examined depending on the
-                    value of the -tolfunmethod.
-                </para>
-                <variablelist>
-                    <varlistentry>
-                        <term>"disabled"</term>
-                        <listitem>
-                            <para>then the tolerance on f is just skipped.</para>
-                        </listitem>
-                    </varlistentry>
-                    <varlistentry>
-                        <term>"enabled"</term>
-                        <listitem>
-                            <para>if the following condition</para>
-                            <programlisting role="example">
-                                abs(currentfopt) &lt; tolfunrelative * abs(previousfopt) + tolfunabsolute
-                            </programlisting>
-                            <para>is true, then the status is set to "tolf" and terminate is
-                                set to %t.
-                            </para>
-                        </listitem>
-                    </varlistentry>
-                </variablelist>
-                <para>The relative termination criteria on the function value works
-                    well if the function value at optimum is near zero. In that case, the
-                    function value at initial guess fx0 may be used as
-                    previousfopt.
-                </para>
-                <para>The absolute termination criteria on the function value works if
-                    the user has an accurate idea of the optimum function value.
-                </para>
-            </listitem>
-            <listitem>
-                <para>The tolerance on x is examined depending on the value of the
-                    -tolxmethod.
-                </para>
-                <variablelist>
-                    <varlistentry>
-                        <term>%f</term>
-                        <listitem>
-                            <para>then the tolerance on x is just skipped.</para>
-                        </listitem>
-                    </varlistentry>
-                    <varlistentry>
-                        <term>%t</term>
-                        <listitem>
-                            <para>if the following condition</para>
-                            <programlisting role="example">
-                                norm(currentxopt - previousxopt) &lt; tolxrelative * norm(currentxopt) + tolxabsolute
-                            </programlisting>
-                            <para>is true, then the status is set to "tolx" and terminate is
-                                set to %t.
-                            </para>
-                        </listitem>
-                    </varlistentry>
-                </variablelist>
-                <para>The relative termination criteria on x works well if x at
-                    optimum is different from zero. In that case, the condition measures
-                    the distance between two iterates.
-                </para>
-                <para>The absolute termination criteria on x works if the user has an
-                    accurate idea of the scale of the optimum x. If the optimum x is near
-                    0, the relative tolerance will not work and the absolute tolerance is
-                    more appropriate.
-                </para>
-            </listitem>
-        </itemizedlist>
-    </refsection>
-    <refsection>
-        <title>Example : Setting up an optimization</title>
-        <para>In the following example, one searches the minimum of the 2D
-            Rosenbrock function. One begins by defining the function "rosenbrock"
-            which computes the Rosenbrock function. The traditionnal initial guess
-            [-1.2 1.0] is used. The initial simplex is computed along the axes with a
-            length equal to 0.1. The Nelder-Mead algorithm with variable simplex size
-            is used. The verbose mode is enabled so that messages are generated during
-            the algorithm. After the optimization is performed, the optimum is
-            retrieved with quiery features.
-        </para>
-        <programlisting role="example">
-            function [ f , index ] = rosenbrock ( x , index )
-            f = 100*(x(2)-x(1)^2)^2 + (1-x(1))^2;
-            endfunction
-            
-            opt = optimbase_new();
-            opt = optimbase_configure(opt,"-numberofvariables",2);
-            nbvar = optimbase_cget(opt,"-numberofvariables");
-            opt = optimbase_configure(opt,"-function",rosenbrock);
-            [ opt , f , index ] = optimbase_function ( opt , [0.0 0.0] , 1 );
-            expectedf = 1
-            disp(f)
-            opt = optimbase_destroy(opt);
-        </programlisting>
-    </refsection>
-    <refsection>
-        <title>Example : Passing extra parameters</title>
-        <para>In the following example, we consider a function which has two
-            additionnal parameters <literal>a</literal> and <literal>b</literal>. In
-            this case, we can configure the "-function" option as a list, where the
-            first element is the function and the two extra arguments are located at
-            the end of the list.
-        </para>
-        <programlisting role="example">
-            function [ f , index ] = rosenbrock2 ( x , index , a , b )
-            f = a*(x(2)-x(1)^2)^2 + (b-x(1))^2;
-            endfunction
-            
-            opt = optimbase_new();
-            opt = optimbase_configure(opt,"-numberofvariables",2);
-            nbvar = optimbase_cget(opt,"-numberofvariables");
-            a = 100;
-            b = 1;
-            opt = optimbase_configure(opt,"-function",list(rosenbrock2,a,b));
-            [ opt , f , index ] = optimbase_function ( opt , [0.0 0.0] , 1 );
-            expectedf = 1
-            disp(f)
-            opt = optimbase_destroy(opt);
-        </programlisting>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_cget.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_cget.xml
new file mode 100644 (file)
index 0000000..e612753
--- /dev/null
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_cget" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_cget</refname>
+        <refpurpose>Returns the value for the given key.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            value = optimbase_cget(opt, key)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>key </term>
+                <listitem>
+                    <para>A string, the name of the key to quiery.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>value </term>
+                <listitem>
+                    <para>the value in fonction of the given key.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_cget</literal> function returns the value contained in the 
+            <literal>key</literal>. If the <literal>key</literal> is unknown, this function generates 
+            an error. 
+        </para>
+        <para>
+            To know the list of available keys, go to <literal>optimbase_configure</literal> help page.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    // Set number of variables
+    opt = optimbase_configure ( opt , "-numberofvariables" , 10);
+    nbvar = optimbase_cget(opt, "-numberofvariables")
+
+    // Set initial guess
+    opt = optimbase_configure(opt, "-x0", [-1.2 1.0]');
+    x0 = optimbase_cget(opt, "-x0")
+
+    // Set maximum number of iteration
+    opt = optimbase_configure(opt, "-maxiter", 200);
+    value = optimbase_cget(opt, "-maxiter")
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_new">optimbase_new</link>
+            </member>
+            <member>
+                <link linkend="optimbase_configure">optimbase_configure</link>
+            </member>
+            <member>
+                <link linkend="optimbase_get">optimbase_get </link>
+            </member>
+            <member>
+                <link linkend="optimbase_histget">optimbase_histget </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_checkbounds.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_checkbounds.xml
new file mode 100644 (file)
index 0000000..8ef7f94
--- /dev/null
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_checkbounds" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_checkbounds</refname>
+        <refpurpose>Checks the bounds.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_checkbounds(opt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_checkbounds</literal> function checks if the bounds are 
+            consistent and produces an error message if not.
+        </para>
+        <para>
+            To have a consistency of bounds, you must satisfy the two conditions: 
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    the number of maximal and minimal bounds must be the same as the number of variables,
+                </para>
+            </listitem>
+            <listitem>
+                <para>minimal bounds must be lower than maximal bounds ,</para>
+            </listitem>
+        </itemizedlist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+    // Set number of variables
+    opt = optimbase_configure ( opt, "-numberofvariables", 2);
+
+    // Set minimal and maximal bounds
+    opt = optimbase_configure(opt, "-boundsmin", [-5 -5]');
+    opt = optimbase_configure(opt, "-boundsmax", [5 5]');
+
+    // Set check bounds
+    opt = optimbase_checkbounds(opt)
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_isinbounds">optimbase_isinbounds</link>
+            </member>
+            <member>
+                <link linkend="optimbase_hasbounds">optimbase_hasbounds</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_checkcostfun.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_checkcostfun.xml
new file mode 100644 (file)
index 0000000..d14c3ac
--- /dev/null
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_checkcostfun" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_checkcostfun</refname>
+        <refpurpose>Checks the cost function.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_checkcostfun(opt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_checkcostfun</literal> function checks that the cost function 
+            is correctly connected. This function generates an error if the cost function is not 
+            connected. 
+        </para>
+        <para>
+            This function takes into account for the cost function at the initial guess x0 only. 
+            She checks that all values of the index argument are valid. If there are non-linear 
+            constraints, <literal>optimbase_checkcostfun</literal> checks that the matrix has the 
+            correct shape.
+        </para>
+        <para>
+            This function requires at least one call to the cost function to make the necessary checks.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    function [ y , index ] = rosenbrock ( x , index )
+        y = 100*(x(2)-x(1)^2)^2 + (1-x(1))^2;
+    endfunction
+
+    opt = optimbase_new ();
+    opt = optimbase_configure(opt,"-numberofvariables",2);
+    opt = optimbase_configure(opt,"-x0",[1.1 1.1]');
+    opt = optimbase_configure(opt,"-function",rosenbrock);
+    opt = optimbase_checkcostfun(opt)
+    opt = optimbase_destroy(opt);
+
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_function">optimbase_function</link>
+            </member>
+            <member>
+                <link linkend="optimbase_configure">optimbase_configure</link>
+            </member>
+            <member>
+                <link linkend="optimbase_new">optimbase_new </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_checkx0.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_checkx0.xml
new file mode 100644 (file)
index 0000000..4a342de
--- /dev/null
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_checkx0" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_checkx0</refname>
+        <refpurpose>Checks initial guess.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_checkx0(opt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_checkx0</literal> function checks if the initial guess is 
+            consistent with the bounds and the non-linear inequality constraints,      if any and
+            produces an error message if not.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    opt = optimbase_configure ( opt, "-numberofvariables", 2);
+    opt = optimbase_configure ( opt , "-verbose",1);
+       opt = optimbase_configure ( opt , "-boundsmin" , [-5.0 -5.0] );
+    opt = optimbase_configure ( opt , "-boundsmax" , [5.0 5.0] );
+    opt = optimbase_configure ( opt , "-x0", [1.0 1.0]' );
+
+    // Check x0
+    opt = optimbase_checkx0(opt)
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_isfeasible">optimbase_isfeasible</link>
+            </member>
+            <member>
+                <link linkend="optimbase_configure">optimbase_configure</link>
+            </member>
+            <member>
+                <link linkend="optimbase_cget">optimbase_cget</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_configure.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_configure.xml
new file mode 100644 (file)
index 0000000..b7ee550
--- /dev/null
@@ -0,0 +1,275 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_configure" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_configure</refname>
+        <refpurpose>Configures the current object.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_configure(opt, key, value)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The current object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>key </term>
+                <listitem>
+                    <para>A string.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>value </term>
+                <listitem>
+                    <para>
+                        The value is assigned in function of <literal>key</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_configure</literal> function allows to set the value contained in
+            the <literal>key</literal>.
+        </para>
+        <para>
+            The following keys are available :
+        </para>
+        <variablelist>
+            <varlistentry>
+                <term>-verbose </term>
+                <listitem>
+                    <para>
+                        A 1-by-1 matrix of doubles, positive, integer value, set to 1 to enable 
+                        verbose logging (default <literal>-verbose</literal> = 0).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-verbosetermination </term>
+                <listitem>
+                    <para>
+                        A 1-by-1 matrix of doubles, positive, integer value, set to 1 to enable 
+                        verbose termination logging (default <literal>-verbosetermination</literal> = 0).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-x0 </term>
+                <listitem>
+                    <para>
+                        The initial guess. A n-by-1 matrix of doubles, where n is the number of 
+                        variables. There is no default value, i.e. the user must provide <literal>-x0</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-maxfunevals </term>
+                <listitem>
+                    <para>
+                        The maximum number of function evaluations is a 1-by-1 matrix of doubles, 
+                        positive, integer value (default <literal>-maxfunevals</literal> = 100).
+                        If this criteria is triggered, the status of the optimization is set to 
+                        <literal>-maxfunevals</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-maxiter </term>
+                <listitem>
+                    <para>
+                        The maximum number of iterations is a 1-by-1 matrix of doubles, positive, 
+                        integer value (default <literal>-maxiter</literal> = 100).
+                        If this criteria is triggered, the status of the optimization is set to 
+                        <literal>-maxiter</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-tolfunabsolute </term>
+                <listitem>
+                    <para>
+                        The absolute tolerance for the function value is a 1-by-1 matrix of 
+                        doubles, positive (default <literal>-tolfunabsolute</literal> = 0).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-tolfunrelative </term>
+                <listitem>
+                    <para>The relative tolerance for the function value is a 1-by-1 matrix of 
+                        doubles, positive (default <literal>-tolfunrealtive</literal> = %eps).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-tolfunmethod </term>
+                <listitem>
+                    <para>
+                        A 1-by-1 matrix of booleans. Set to %t to enable termination with 
+                        tolerance on function value (default <literal>-tolfunmethod</literal> = %f).
+                        If this criteria is triggered, the status of the optimization is set to "tolf".
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-tolxabsolute </term>
+                <listitem>
+                    <para>
+                        The absolute tolerance on x is a 1-by-1 matrix of doubles, positive 
+                        (default <literal>-tolxabsolute</literal> = 0).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-tolxrelative </term>
+                <listitem>
+                    <para>
+                        The relative tolerance on x is a 1-by-1 matrix of doubles, positive 
+                        (default <literal>-tolxrealtive</literal> = sqrt(%eps)).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-tolxmethod </term>
+                <listitem>
+                    <para>
+                        A 1-by-1 matrix of booleans. Set to %t to enable the tolerance on x in 
+                        the termination criteria (default <literal>-tolxmethod</literal> = %t).
+                        If this criteria is triggered, the status of the optimization is set to "tolx".
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-function </term>
+                <listitem>
+                    <para>
+                        A function or a list, the objective function. This function computes the value 
+                        of the cost and the non linear constraints, if any.
+                        There is no default value, i.e. the user must provide <literal>f</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-outputcommand </term>
+                <listitem>
+                    <para>
+                        A function or a list. The function is called back for output.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-numberofvariables </term>
+                <listitem>
+                    <para>
+                        The number of variables to optimize is a 1-by-1 matrix of doubles, positive, 
+                        integer value (default <literal>-numberofvariables</literal> = 0).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-storehistory </term>
+                <listitem>
+                    <para>
+                        A 1-by-1 matrix of doubles, positive, integer value. Set to %t to enable the 
+                        history storing (default <literal>-storehistory</literal> = %f).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-boundsmin </term>
+                <listitem>
+                    <para>
+                        The minimum bounds for the parameters. A n-by-1 matrix of doubles where n 
+                        is the number of variables (default <literal>-boundsmin</literal> = [],
+                        i.e. there are no minimim bounds).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-boundsmax </term>
+                <listitem>
+                    <para>
+                        The maximum bounds for the parameters. A n-by-1 matrix of doubles where n 
+                        is the number of variables (default <literal>-boundsmax</literal> = [], 
+                        i.e. there are no maximum bounds).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-nbineqconst </term>
+                <listitem>
+                    <para>
+                        The number of inequality constraints is a 1-by-1 matrix of doubles, positive, 
+                        integer value (default <literal>-nbineqconst</literal> = 0).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-logfile </term>
+                <listitem>
+                    <para>The name of the log file.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-withderivatives </term>
+                <listitem>
+                    <para>
+                        A 1-by-1 matrix of booleans. Set to %t if the algorithm uses derivatives 
+                        (default <literal>-withderivatives</literal> = 0).
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    // Set number of variables
+    opt = optimbase_configure ( opt , "-numberofvariables" , 10)
+
+    // Set initial guess
+    opt = optimbase_configure(opt, "-x0", [-1.2 1.0]')
+
+    // Set maximum number of iteration
+    opt = optimbase_configure(opt,"-maxiter",200)
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_new">optimbase_new</link>
+            </member>
+            <member>
+                <link linkend="optimbase_cget">optimbase_cget </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_destroy.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_destroy.xml
new file mode 100644 (file)
index 0000000..f4d2ac3
--- /dev/null
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_destroy" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_destroy</refname>
+        <refpurpose>Resets the historyfopt and historyxopt fields of an object.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_destroy(opt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_destroy</literal> function resets the <literal>historyfopt</literal> 
+            and <literal>historyxopt</literal> fields at empty matrix ([]). 
+        </para>
+        <para>
+            If the <literal>-logstartup</literal> option is set to true (%t), the 
+            <literal>optimbase_logshutdown</literal> function is called. She sets the
+            <literal>-logstartup</literal> option at false (%f) and close the log file if the 
+            <literal>-logfile</literal> option is different to empty string.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+    opt = optimbase_configure ( opt , "-storehistory" , %t );
+    opt = optimbase_histset ( opt , 1 , "-xopt" , [1.0 1.0]' );
+    val = optimbase_get(opt, "-historyxopt")
+    opt = optimbase_destroy(opt);
+    val = optimbase_get(opt, "-historyxopt")
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_new">optimbase_new</link>
+            </member>
+            <member>
+                <link linkend="optimbase_configure">optimbase_configure</link>
+            </member>
+            <member>
+                <link linkend="optimbase_get">optimbase_get</link>
+            </member>
+            <member>
+                <link linkend="optimbase_cget">optimbase_cget </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_function.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_function.xml
new file mode 100644 (file)
index 0000000..ef8f393
--- /dev/null
@@ -0,0 +1,369 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_function" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_function</refname>
+        <refpurpose>Calls cost function.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            [opt, f, index] = optimbase_function(opt, x, index)
+            [opt, f, c, index] = optimbase_function(opt, x, index)
+            [opt, f, g, index] = optimbase_function(opt, x, index)
+            [opt, f, g, c, gc, index] = optimbase_function(opt, x, index)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>
+                        The object of TOPTIM type (tlist). (INPUT/OUTPUT)
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>x </term>
+                <listitem>
+                    <para>
+                        A column vector of doubles, the current point.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>index </term>
+                <listitem>
+                    <para>
+                        An integer. (INPUT/OUTPUT)
+                    </para>
+                    <para>
+                        The index input parameter has the following meaning.
+                    </para>
+                    <itemizedlist>
+                        <listitem>
+                            <para>
+                                index = 1: nothing is to be computed, the user may display messages, for example.
+                            </para>
+                        </listitem>
+                        <listitem>
+                            <para>
+                                index = 2: compute f.
+                            </para>
+                        </listitem>
+                        <listitem>
+                            <para>
+                                index = 3: compute g.
+                            </para>
+                        </listitem>
+                        <listitem>
+                            <para>
+                                index = 4: compute f and g.
+                            </para>
+                        </listitem>
+                        <listitem>
+                            <para>
+                                index = 5: compute c.
+                            </para>
+                        </listitem>
+                        <listitem>
+                            <para>
+                                index = 6: compute f and c.
+                            </para>
+                        </listitem>
+                        <listitem>
+                            <para>
+                                index = 7: compute f, g, c and gc.
+                            </para>
+                        </listitem>
+                    </itemizedlist>
+                    <para>
+                        The index output parameter has the following meaning
+                        .
+                    </para>
+                    <itemizedlist>
+                        <listitem>
+                            <para>
+                                index &gt; 0: everything is fine.
+                            </para>
+                        </listitem>
+                        <listitem>
+                            <para>
+                                index = 0: the optimization must stop.
+                            </para>
+                        </listitem>
+                        <listitem>
+                            <para>
+                                index &lt; 0: one function could not be evaluated.
+                            </para>
+                        </listitem>
+                    </itemizedlist>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>f </term>
+                <listitem>
+                    <para>
+                        Scalar. The value of the cost function.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>g </term>
+                <listitem>
+                    <para>
+                        Row matrix of doubles. The gradient of the cost function.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>c </term>
+                <listitem>
+                    <para>
+                        Row matrix of doubles. The non-linear, positive, inequality constraints.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>gc </term>
+                <listitem>
+                    <para>
+                        Matrix of doubles. The gradient of the non-linear, positive, inequality constraints.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_function</literal> function calls the cost function and return 
+            the required results. If a cost function additional argument is defined in current 
+            object, it is passed it to the function as the last argument.
+        </para>
+        <para>
+            The <literal>-function()</literal> option allows to configure the cost function. 
+            The cost function is used, dependind on the context,       to compute the cost, the 
+            non-linear inequality positive constraints, the gradient of the function and 
+            the gradient of the non-linear inequality constraints.
+        </para>
+        <para>
+            The cost function can also be used to produce outputs and to terminate an 
+            optimization algorithm.
+        </para>
+        <para>
+            Each calling sequence of the <literal>optimbase_function</literal> function corresponds 
+            to a specific calling sequence of the user-provided cost function.
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    If the <literal>-withderivatives</literal> is false and there is no non-linear
+                    constraint, the calling sequence is
+                </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                    [ this , f , index ] = optimbase_function ( this , x , index )
+                ]]>
+                </programlisting>
+                <para>which corresponds to the cost functions: </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                    [f , index ] = costf( x , index )
+                ]]>
+                </programlisting>
+            </listitem>
+            <listitem>
+                <para>
+                    If the <literal>-withderivatives</literal> is false and there are non-linear constraints, 
+                    the calling sequence is
+                </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                    [ this , f , c , index ] = optimbase_function ( this , x , index )
+                ]]>
+                </programlisting>
+                <para>
+                    which corresponds to the cost functions: 
+                </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                    [f , c , index ] = costf( x , index )
+                ]]>
+                </programlisting>
+            </listitem>
+            <listitem>
+                <para>
+                    If the <literal>-withderivatives</literal> is true and there is no non-linear constraint, 
+                    the calling sequence is
+                </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                    [ this , f , g , index ] = optimbase_function ( this , x , index )
+                ]]>
+                </programlisting>
+                <para>
+                    which corresponds to the cost functions: 
+                </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                    [f , g , index ] = costf( x , index )
+                ]]>
+                </programlisting>
+            </listitem>
+            <listitem>
+                <para>
+                    If the <literal>-withderivatives</literal> is true and there are non-linear constraints, 
+                    the calling sequence is
+                </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                    [ this , f , g , c , gc , index ] = optimbase_function ( this , x , index )
+                ]]>
+                </programlisting>
+                <para>
+                    which corresponds to the cost functions: 
+                </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                    [f , g , c , gc , index ] = costf( x , index )
+                ]]>
+                </programlisting>
+            </listitem>
+        </itemizedlist>
+        <para>
+            Each calling sequence corresponds to a particular class of algorithms, includinf for e
+            xample
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    unconstrained, derivative-free algorithms,
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    unconstrained constrained, derivative-free algorithms,
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    unconstrained, derivative-based algorithms,
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    nonlinearily constrained, derivative-based algorithms,
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    etc.
+                </para>
+            </listitem>
+        </itemizedlist>
+        <para>
+            It might happen that the function requires additional arguments to be evaluated. 
+            In this case, we can use the following feature. The argument <literal>fun</literal> 
+            can also be the list <literal>(f, a1, a2, ...)</literal>. 
+            In this case <literal>f</literal>, the first element in the list, must bea function and 
+            must have the header:
+        </para>
+        <programlisting role="no-scilab-exec">
+            <![CDATA[ 
+                    [ f , index ] = f ( x , index , a1 , a2 , ... )
+                [ f , c , index ] = f ( x , index , a1 , a2 , ... )
+                [ f , g , index ] = f ( x , index , a1 , a2 , ... )
+                [ f , g , c , gc , index ] = f ( x , index , a1 , a2 , ... )
+                ]]>
+        </programlisting>
+        <para>
+            where the input arguments <literal>a1, a2, ...</literal> are automatically appended at 
+            the end of the calling sequence.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example : Setting up an optimization</title>
+        <para>In the following example, one searches the minimum of the 2D
+            Rosenbrock function. One begins by defining the function "rosenbrock"
+            which computes the Rosenbrock function. The traditionnal initial guess
+            [-1.2 1.0] is used. The initial simplex is computed along the axes with a
+            length equal to 0.1. The Nelder-Mead algorithm with variable simplex size
+            is used. The verbose mode is enabled so that messages are generated during
+            the algorithm. After the optimization is performed, the optimum is
+            retrieved with quiery features.
+        </para>
+        <programlisting role="example">
+            <![CDATA[ 
+            function [ f , index ] = rosenbrock ( x , index )
+            f = 100*(x(2)-x(1)^2)^2 + (1-x(1))^2;
+            endfunction
+            
+            opt = optimbase_new();
+            opt = optimbase_configure(opt,"-numberofvariables",2);
+            nbvar = optimbase_cget(opt,"-numberofvariables");
+            opt = optimbase_configure(opt,"-function",rosenbrock);
+            [ opt , f , index ] = optimbase_function ( opt , [0.0 0.0] , 1 );
+            expectedf = 1
+            disp(f)
+            opt = optimbase_destroy(opt);
+        ]]>
+        </programlisting>
+    </refsection>
+    <refsection>
+        <title>Example : Passing extra parameters</title>
+        <para>In the following example, we consider a function which has two
+            additional parameters <literal>a</literal> and <literal>b</literal>. In
+            this case, we can configure the "-function" option as a list, where the
+            first element is the function and the two extra arguments are located at
+            the end of the list.
+        </para>
+        <programlisting role="example">
+            <![CDATA[ 
+            function [ f , index ] = rosenbrock2 ( x , index , a , b )
+            f = a*(x(2)-x(1)^2)^2 + (b-x(1))^2;
+            endfunction
+            
+            opt = optimbase_new();
+            opt = optimbase_configure(opt,"-numberofvariables",2);
+            nbvar = optimbase_cget(opt,"-numberofvariables");
+            a = 100;
+            b = 1;
+            opt = optimbase_configure(opt,"-function",list(rosenbrock2,a,b));
+            [ opt , f , index ] = optimbase_function ( opt , [0.0 0.0] , 1 );
+            expectedf = 1
+            disp(f)
+            opt = optimbase_destroy(opt);
+         ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_new">optimbase_new</link>
+            </member>
+            <member>
+                <link linkend="optimbase_configure">optimbase_configure</link>
+            </member>
+            <member>
+                <link linkend="optimbase_destroy">optimbase_destroy </link>
+            </member>
+            <member>
+                <link linkend="optimbase_checkcostfun">optimbase_checkcostfun </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_get.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_get.xml
new file mode 100644 (file)
index 0000000..a19798b
--- /dev/null
@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_get" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_get</refname>
+        <refpurpose>Returns the value for the given key.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            value = optimbase_set(opt, key)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>key </term>
+                <listitem>
+                    <para>A string, the name of the key to set.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>value </term>
+                <listitem>
+                    <para>the value in fonction of the given key.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_get</literal> function returns the value for the given key. 
+            If the key is unknown, this function generates an error.
+        </para>
+        <para>
+            The list of available keys is the same as the optimbase_set function:
+        </para>
+        <variablelist>
+            <varlistentry>
+                <term>-funevals </term>
+                <listitem>
+                    <para>
+                        The number of function evaluations is a 1-by-1 matrix of doubles, 
+                        positive, integer value.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-iterations </term>
+                <listitem>
+                    <para>
+                        The number of iterations is a 1-by-1 matrix of doubles, positive, 
+                        integer value.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-xopt </term>
+                <listitem>
+                    <para>
+                        The x optimum.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-fopt </term>
+                <listitem>
+                    <para>
+                        The optimum cost function value.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-historyxopt </term>
+                <listitem>
+                    <para>
+                        An array, with nbiter values, containing the history of x during the iterations.
+                    </para>
+                    <para>
+                        This array is available after optimization if the history storing was enabled with 
+                        the <literal>-storehistory</literal> option.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-historyfopt </term>
+                <listitem>
+                    <para>
+                        An array, with nbiter values, containing the history of the function value during 
+                        the iterations.
+                    </para>
+                    <para>
+                        This array is available after optimization if the history storing was enabled with 
+                        the <literal>-storehistory</literal> option.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-fx0 </term>
+                <listitem>
+                    <para>
+                        The function value for the initial guess.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-status </term>
+                <listitem>
+                    <para>
+                        A string containing the status of the optimization.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-logstartup </term>
+                <listitem>
+                    <para>
+                        A 1-by-1 matrix of booleans. Set to %t when the logging is started up 
+                        (default <literal>-logstartup</literal> = %f).
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+    
+    // Set optimum
+    opt = optimbase_set(opt,"-xopt",[1.0 1.0]) ;
+    // Get optimum
+    val = optimbase_get(opt, "-xopt")
+
+    // Set function value at optimum
+    opt = optimbase_set(opt,"-fopt",1.0);
+    // Get function value at optimum
+    val = optimbase_get(opt, "-fopt")
+
+    // Set status
+    opt = optimbase_set(opt,"-status","maxiter");
+    // Get status
+    val = optimbase_get(opt, "-status")
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_set">optimbase_set</link>
+            </member>
+            <member>
+                <link linkend="optimbase_cget">optimbase_cget</link>
+            </member>
+            <member>
+                <link linkend="optimbase_histget">optimbase_histget </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_hasbounds.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_hasbounds.xml
new file mode 100644 (file)
index 0000000..03f95d7
--- /dev/null
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_hasbounds" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_hasbounds</refname>
+        <refpurpose>Checks if the bounds are specified.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            [opt, hasbounds] = optimbase_hasbounds(opt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>hasbounds </term>
+                <listitem>
+                    <para>A boolean.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_hasbounds</literal> function returns %t if current problem has 
+            bounds.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    // Set number of variables
+    opt = optimbase_configure ( opt, "-numberofvariables", 2);
+    
+    // Set minimal and maximal bounds
+    opt = optimbase_configure(opt, "-boundsmin",[-5 -5]');
+    opt = optimbase_configure(opt, "-boundsmax",[5 5]');
+
+    // Check if the bounds are specified
+    [opt, hasbounds] = optimbase_hasbounds (opt);
+    disp(hasbounds)
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_hasconstraints">optimbase_hasconstraints</link>
+            </member>
+            <member>
+                <link linkend="optimbase_hasnlcons">optimbase_hasnlcons</link>
+            </member>
+            <member>
+                <link linkend="optimbase_checkbounds">optimbase_checkbounds</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_hasconstraints.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_hasconstraints.xml
new file mode 100644 (file)
index 0000000..6c99503
--- /dev/null
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_hasconstraints" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_hasconstraints</refname>
+        <refpurpose>Checks if the constraints are specified.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            [opt, hascons] = optimbase_hasbounds(opt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>hascons </term>
+                <listitem>
+                    <para>A boolean.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_hasconstraints</literal> function returns %t if current problem 
+            has bounds constraints, linear constraints or non-linear constraints.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example 1</title>
+        <programlisting role="example">
+            <![CDATA[ 
+       opt = optimbase_new();
+       
+       // Set number of variables
+       opt = optimbase_configure ( opt, "-numberofvariables", 2);
+       
+       // Set minimal and maximal bounds
+       opt = optimbase_configure(opt, "-boundsmin",[-5 -5]');
+       opt = optimbase_configure(opt, "-boundsmax",[5 5]');
+       
+       // Check if the bounds are specified
+       [opt, hascons] = optimbase_hasconstraints (opt);
+       disp(hascons)
+
+       opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+        <title>Example 2</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    // Set number of variables
+    opt = optimbase_configure ( opt, "-numberofvariables", 2);
+
+    // Set non linear constraint
+    opt = optimbase_configure(opt, "-verbose", 1);
+    opt = optimbase_configure(opt, "-nbineqconst", 4);
+
+    // Check if the non linear constraints are specified
+    [opt, hascons] = optimbase_hasconstraints (opt);
+    disp(hascons)
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_hasbounds">optimbase_hasbounds</link>
+            </member>
+            <member>
+                <link linkend="optimbase_hasnlcons">optimbase_hasnlcons</link>
+            </member>
+            <member>
+                <link linkend="optimbase_isinbounds">optimbase_isinbounds </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_hasnlcons.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_hasnlcons.xml
new file mode 100644 (file)
index 0000000..ad14a66
--- /dev/null
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_hasnlcons" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_hasnlcons</refname>
+        <refpurpose>Checks if the non linear constraints are specified.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            [opt, hasnlcons] = optimbase_hasnlcons(opt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>hascons </term>
+                <listitem>
+                    <para>A boolean.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_hasnlcons</literal> function returns %t if current problem 
+            has non-linear constraints.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    // Set number of variables
+    opt = optimbase_configure ( opt, "-numberofvariables", 2);
+    
+    // Set non linear constraints
+    opt = optimbase_configure(opt, "-verbose", 1);
+    opt = optimbase_configure(opt, "-nbineqconst", 4);
+
+    // Check if the bounds are specified
+    [opt, hasnlcons] = optimbase_hasnlcons (opt);
+    disp(hasnlcons)
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_hasbounds">optimbase_hasbounds</link>
+            </member>
+            <member>
+                <link linkend="optimbase_hasconstraints">optimbase_hasconstraints</link>
+            </member>
+            <member>
+                <link linkend="optimbase_isinnonlincons">optimbase_isinnonlincons</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_histget.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_histget.xml
new file mode 100644 (file)
index 0000000..b4a04cb
--- /dev/null
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_histget" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_histget</refname>
+        <refpurpose>Returns the history value.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            value = optimbase_histget(opt, iter, key)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>iter </term>
+                <listitem>
+                    <para>An integer. The iteration number to get.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>key </term>
+                <listitem>
+                    <para>A string. The name of the key to quiery.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>value </term>
+                <listitem>
+                    <para>A 1-by-1 matrix of doubles. The value to get.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_histget</literal> function returns the history value at the given 
+            iteration number for the given key.
+            If the key is unknown, this function generates an error.
+        </para>
+        <para>
+            The list of available keys is the same as the <literal>optimbase_histset</literal> :
+        </para>
+        <variablelist>
+            <varlistentry>
+                <term>-xopt </term>
+                <listitem>
+                    <para>The x optimum.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-fopt </term>
+                <listitem>
+                    <para>The optimum cost function value.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    opt = optimbase_configure ( opt , "-storehistory" , %t );
+    opt = optimbase_histset ( opt , 1 , "-xopt" , [1.0 1.0]' );
+    x0 = optimbase_histget ( opt , 1 , "-xopt" )
+    fopt = optimbase_get(opt,"-fopt")
+    opt = optimbase_histset ( opt , 1 , "-fopt" , 1.0 );
+    f0 = optimbase_histget ( opt , 1 , "-fopt" )
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_histset">optimbase_histset</link>
+            </member>
+            <member>
+                <link linkend="optimbase_get">optimbase_get</link>
+            </member>
+            <member>
+                <link linkend="optimbase_cget">optimbase_cget </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_histset.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_histset.xml
new file mode 100644 (file)
index 0000000..46e00c9
--- /dev/null
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_histset" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_histset</refname>
+        <refpurpose>Set the history value at given iteration for the given key.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_histset(opt, iter, key, value)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>iter </term>
+                <listitem>
+                    <para>An integer. The iteration number to get.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>key </term>
+                <listitem>
+                    <para>A string. The name of the key to quiery.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>value </term>
+                <listitem>
+                    <para>A 1-by-1 matrix of doubles. The value to set.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_histset</literal> function sets the history value at given 
+            iteration for the given key.
+            If the key is unknown, this function generates an error.
+        </para>
+        <para>
+            The list of available keys is the following :
+        </para>
+        <variablelist>
+            <varlistentry>
+                <term>-xopt </term>
+                <listitem>
+                    <para>The x optimum.</para>
+                </listitem>
+                <term>-fopt </term>
+                <listitem>
+                    <para>The optimum cost function value.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    opt = optimbase_configure ( opt , "-storehistory" , %t );
+    opt = optimbase_histset ( opt , 1 , "-xopt" , [1.0 1.0]' );
+    x0 = optimbase_histget ( opt , 1 , "-xopt" )
+    fopt = optimbase_get(opt,"-fopt")
+    opt = optimbase_histset ( opt , 1 , "-fopt" , 1.0 );
+    f0 = optimbase_histget ( opt , 1 , "-fopt" )
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_histget">optimbase_histget</link>
+            </member>
+            <member>
+                <link linkend="optimbase_set">optimbase_set</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_incriter.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_incriter.xml
new file mode 100644 (file)
index 0000000..d1a4235
--- /dev/null
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_incriter" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_incriter</refname>
+        <refpurpose>Increments the number of iterations.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_incriter(opt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_incriter</literal> function increments the number of iterations.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    xopt = optimbase_get ( opt, "-iterations")
+    opt = optimbase_incriter ( opt );
+    xopt = optimbase_get ( opt, "-iterations")
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_new">optimbase_new</link>
+            </member>
+            <member>
+                <link linkend="optimbase_get">optimbase_get</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_isfeasible.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_isfeasible.xml
new file mode 100644 (file)
index 0000000..b9aa2b9
--- /dev/null
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_isfeasible" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_isfeasible</refname>
+        <refpurpose>Checks if the point satisfies constraints.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            [opt, isfeasible] = optimbase_isfeasible(opt, x)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>x </term>
+                <listitem>
+                    <para>A vector of doubles. The current point.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>isfeasible </term>
+                <listitem>
+                    <para>An integer either -1, 0 or 1.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_isfeasible</literal> function checks if the point 
+            <literal>x</literal> satisfies the bounds and inequality constraints.
+        </para>
+        <para>
+            This function returns
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    1 if the given point satisfies bounds constraints ans inequality constraints,
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    0 if the given point is not in the bounds,
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    -1 if the given point does not satisfies inequality constraints.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new ();
+    opt = optimbase_configure(opt, "-numberofvariables", 2);
+    opt = optimbase_configure(opt, "-verbose", 1);
+    opt = optimbase_configure ( opt , "-boundsmin" , [-5 -5] );
+    opt = optimbase_configure ( opt , "-boundsmax" , [5 5] );
+    [ opt , isfeasible ] = optimbase_isfeasible ( opt ,  [0 0] );
+    disp(isfeasible)
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_checkx0">optimbase_checkx0</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_isinbounds.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_isinbounds.xml
new file mode 100644 (file)
index 0000000..f0ff97b
--- /dev/null
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_isinbounds" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_isinbounds</refname>
+        <refpurpose>Checks if the given point satisfies bounds constraints.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            [opt, isfeasible] = optimbase_isinbounds(opt, x)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>x </term>
+                <listitem>
+                    <para>A vector of doubles, the current point.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>isfeasible </term>
+                <listitem>
+                    <para>A boolean.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_isinbounds</literal> function returns <literal>isfeasible</literal> 
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    %t if the given point satisfies bounds constraints.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    %f if the given point is not in the bounds.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new ();
+    opt = optimbase_configure(opt,"-numberofvariables",2);
+    opt = optimbase_configure(opt,"-verbose",1);
+    opt = optimbase_configure ( opt , "-boundsmin" , [-5.0 -5.0] );
+    opt = optimbase_configure ( opt , "-boundsmax" , [5.0 5.0] );
+    [ opt , isfeasible ] = optimbase_isinbounds ( opt ,  [0.0 0.0] );
+    disp(isfeasible)
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_checkbounds">optimbase_checkbounds</link>
+            </member>
+            <member>
+                <link linkend="optimbase_hasbounds">optimbase_hasbounds</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_isinnonlincons.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_isinnonlincons.xml
new file mode 100644 (file)
index 0000000..41bfd2f
--- /dev/null
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_isinnonlincons" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_isinnonlincons</refname>
+        <refpurpose>Checks if the given point satisfies the non-linear constraints.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            [opt, isfeasible] = optimbase_isinnonlincons(opt, x)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>x </term>
+                <listitem>
+                    <para>A vector of doubles, the current point.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>isfeasible </term>
+                <listitem>
+                    <para>A boolean.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_isinnonlincons</literal> function returns <literal>isfeasible</literal> 
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    %t if the given point satisfies the non-linear constraints.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    %f if the given point does not satisfy the non-linear constraints.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new ();
+    opt = optimbase_configure(opt,"-numberofvariables",2);
+    opt = optimbase_configure(opt,"-verbose",1);
+    opt = optimbase_configure ( opt , "-boundsmin" , [-5.0 -5.0] );
+    opt = optimbase_configure ( opt , "-boundsmax" , [5.0 5.0] );
+    [ opt , isfeasible ] = optimbase_isinnonlincons ( opt ,  [0.0 0.0] );
+    disp(isfeasible)
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_checkbounds">optimbase_checkbounds</link>
+            </member>
+            <member>
+                <link linkend="optimbase_hasnlcons">optimbase_hasnlcons</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_log.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_log.xml
new file mode 100644 (file)
index 0000000..fd090c4
--- /dev/null
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_log" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_log</refname>
+        <refpurpose>Prints the given message.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_log(opt, msg)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>msg </term>
+                <listitem>
+                    <para>A string. The message to print.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_log</literal> function prints the given message in the console, 
+            if verbose logging is enabled. If verbose logging is disabled, does nothing. 
+            If the <literal>-logfile</literal> option has been set, writes the message into the file 
+            instead of writing to the console. If the console is too slow, writing into a file can 
+            be a solution, since it is very fast.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new ();
+    opt = optimbase_configure(opt, "-verbose", 1);
+    optimbase_log ( opt , "My message" );
+    opt = optimbase_destroy(opt);
+
+    // Writes the message into the file 
+    opt = optimbase_new ();
+    opt = optimbase_configure(opt, "-verbose", 1);
+    opt = optimbase_configure(opt,"-logfile",fullfile(TMPDIR,"mylogfile.txt"));
+    myFile = optimbase_cget(opt,"-logfile")
+    optimbase_log ( opt , "My message" );
+    opt = optimbase_destroy(opt)
+
+    fd = mopen( fullfile(TMPDIR,"mylogfile.txt") , "r" );
+    mgetl ( fd , 2 )
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_stoplog">optimbase_stoplog</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_new.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_new.xml
new file mode 100644 (file)
index 0000000..4444c89
--- /dev/null
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_new" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_new</refname>
+        <refpurpose>Creates a new optimization object.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_new()
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The new object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            <literal>optimibase_new()</literal> creates a new optimization object, managing
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>the number of variables,</para>
+            </listitem>
+            <listitem>
+                <para>the minimum and maximum bounds,</para>
+            </listitem>
+            <listitem>
+                <para>the number of non linear inequality constraints,</para>
+            </listitem>
+            <listitem>
+                <para>the logging system,</para>
+            </listitem>
+            <listitem>
+                <para>various termination criteria,</para>
+            </listitem>
+            <listitem>
+                <para>etc.</para>
+            </listitem>
+        </itemizedlist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+    opt = optimbase_configure ( opt , "-numberofvariables",2);
+    iter = optimbase_get(opt, "-iterations")
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_destroy">optimbase_destroy</link>
+            </member>
+            <member>
+                <link linkend="optimbase_configure">optimbase_configure</link>
+            </member>
+            <member>
+                <link linkend="optimbase_cget">optimbase_cget </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_outputcmd.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_outputcmd.xml
new file mode 100644 (file)
index 0000000..2a105ad
--- /dev/null
@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_outputcmd" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_outputcmd</refname>
+        <refpurpose>Calls back user's output command.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            stop = optimbase_outputcmd(opt, state, data)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>state </term>
+                <listitem>
+                    <para>A 1-by-1 matrix of strings, the current state of the algorithm.</para>
+                    <para>Available values are "init, "iter", "done".</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>data </term>
+                <listitem>
+                    <para>A data structure with type T_OPTDATA containing at least the following fields.</para>
+                    <variablelist>
+                        <varlistentry>
+                            <term>x </term>
+                            <listitem>
+                                <para>The current optimum.</para>
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term>fval </term>
+                            <listitem>
+                                <para>The current function value.</para>
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term>iteration </term>
+                            <listitem>
+                                <para>The current iteration index.</para>
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term>funccount</term>
+                            <listitem>
+                                <para>The number of function evaluations.</para>
+                            </listitem>
+                        </varlistentry>
+                    </variablelist>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>stop </term>
+                <listitem>
+                    <para>A 1-by-1 matrix of booleans.</para>
+                    <para>
+                        <literal>stop</literal> is %t if the optimization algorithm must be stopped.
+                    </para>
+                    <para>
+                        <literal>stop</literal> is %f if the optimization algorithm must continue.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_outputcmd</literal> function calls back user's output command. 
+            The <literal>-outputcommand</literal> option allwos to configure a command which is 
+            called back at the start of the optimization, at each iteration and at the end of 
+            the optimization.
+        </para>
+        <para>
+            It might happen that the output function requires additional arguments to be evaluated. 
+            In this case, we can use the following feature. The <literal> outputcmd</literal> argument 
+            can also be the list <literal>(outf, a1, a2, ...)</literal>. In this case <literal>outf</literal>, 
+            the first element in the list, must be a function and must have the header :
+        </para>
+        <programlisting role="no-scilab-exec">
+            <![CDATA[ 
+                 stop = outf(state, data, a1, a2, ....)
+                ]]>
+        </programlisting>
+        <para>
+            where the input arguments <literal>a1, a2, ...</literal> are automatically appended at 
+            the end of the calling sequence.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+function [f,index] = fun(x, index)
+    f = 2*x - 4;
+endfunction
+
+function stop = myoutputcmd(state, data)
+    iter = data.iteration
+    if ( state == "init" ) then
+        mprintf ( "=================================\n");
+        mprintf ( "Initialization\n");
+    elseif ( state == "done" ) then
+        mprintf ( "=================================\n");
+        mprintf ( "End of Optimization\n");
+    end
+    fc = data.funccount
+    fval = data.fval
+    x = data.x
+    mprintf ( "Iter. #%3d, Feval #%3d, Fval = %.1e, x = %s \n" , ..
+    iter, fc, fval, strcat(string(x)," "));
+    stop = %f
+endfunction
+
+a = -5;
+b = 5;
+x0 = (a+b)/2;;
+
+// Creates the object
+opt = optimbase_new();
+
+// Configures the object
+opt = optimbase_configure(opt,"-numberofvariables",2);
+opt = optimbase_configure(opt, "-x0", x0);
+opt = optimbase_configure(opt, "-tolxrelative", 10*%eps);
+opt = optimbase_configure(opt, "-maxiter", 100);
+opt = optimbase_configure(opt, "-function", fun);
+opt = optimbase_configure(opt,"-outputcommand", myoutputcmd);
+
+function x = Dicho(opt,a,b)
+    xk = optimbase_cget(opt, "-x0");
+    [opt, fx0,index] = optimbase_function (opt , xk , 4);
+    opt = optimbase_set ( opt , "-fx0" , fx0 );
+    opt = optimbase_set ( opt , "-xopt" , x0 );
+    opt = optimbase_set ( opt , "-fopt" , fx0 );
+
+    // OutputCmd
+    brutedata = optimbase_outstruct ( opt );
+    data = tlist(["T_OPTBDATA",...
+    "x","fval","iteration","funccount"]);
+    data.x = brutedata.x;
+    data.fval = brutedata.fval;
+    data.iteration = brutedata.iteration;
+    data.funccount = brutedata.funccount;
+    stop = optimbase_outputcmd (opt , "init" , data );
+
+
+    while optimbase_get(opt, "-iterations") <optimbase_cget(opt, "-maxiter")
+        [opt, f,index] = optimbase_function(opt, xk, 4);
+        [opt, g, index] = optimbase_function(opt, a, 4);
+        if g*f <=0 then
+           b = xk;
+        else
+            a = xk;
+        end
+        x = (a+b)/2;
+        opt = optimbase_incriter(opt);
+        opt = optimbase_set ( opt , "-xopt" , x );
+        opt = optimbase_set ( opt , "-fopt" , f );
+        temp = abs(x-xk);
+        
+        if temp < optimbase_cget(opt, "-tolxrelative")
+            // OutputCmd
+            brutedata = optimbase_outstruct ( opt );
+            data = tlist(["T_OPTBDATA",...
+            "x","fval","iteration","funccount"]);
+            data.x = brutedata.x;
+            data.fval = brutedata.fval;
+            data.iteration = brutedata.iteration;
+            data.funccount = brutedata.funccount;
+            stop = optimbase_outputcmd (opt , "done" , data );
+            break
+        end
+        xk = x;
+        
+        // OutputCmd
+        brutedata = optimbase_outstruct ( opt );
+        data = tlist(["T_OPTBDATA",...
+        "x","fval","iteration","funccount"]);
+        data.x = brutedata.x;
+        data.fval = brutedata.fval;
+        data.iteration = brutedata.iteration;
+        data.funccount = brutedata.funccount;
+        stop = optimbase_outputcmd (opt , "iter" , data );
+    end
+
+endfunction
+x = Dicho(opt,a,b)
+]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_outstruct">optimbase_outstruct</link>
+            </member>
+            <member>
+                <link linkend="optimbase_function">optimbase_function</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_outstruct.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_outstruct.xml
new file mode 100644 (file)
index 0000000..28e0dc6
--- /dev/null
@@ -0,0 +1,193 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_outstruct" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_outstruct</refname>
+        <refpurpose>Returns a data structure with type T_OPTDATA.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            data = optimbase_outstruct(opt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>data </term>
+                <listitem>
+                    <para>A data structure with type T_OPTDATA containing at least the following fields.</para>
+                    <variablelist>
+                        <varlistentry>
+                            <term>x </term>
+                            <listitem>
+                                <para>The current optimum.</para>
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term>fval </term>
+                            <listitem>
+                                <para>The current function value.</para>
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term>iteration </term>
+                            <listitem>
+                                <para>The current iteration index.</para>
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term>funccount</term>
+                            <listitem>
+                                <para>The number of function evaluations.</para>
+                            </listitem>
+                        </varlistentry>
+                    </variablelist>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_outstruct</literal> function returns a data structure with 
+            T_OPTDATA type. This data structure contains basic optimization fields.
+        </para>
+        <para>
+            The output argument <literal>data</literal> is designed to be the input of the 
+            <literal>optimbase_outputcmd</literal> function which, in turn, calls back the output 
+            function. This data structure may be enriched by children (specialized) optimization 
+            methods.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+function [f,index] = fun(x, index)
+    f = 2*x - 4;
+endfunction
+
+function stop = myoutputcmd(state, data)
+    iter = data.iteration
+    if ( state == "init" ) then
+        mprintf ( "=================================\n");
+        mprintf ( "Initialization\n");
+    elseif ( state == "done" ) then
+        mprintf ( "=================================\n");
+        mprintf ( "End of Optimization\n");
+    end
+    fc = data.funccount
+    fval = data.fval
+    x = data.x
+    mprintf ( "Iter. #%3d, Feval #%3d, Fval = %.1e, x = %s \n" , ..
+    iter, fc, fval, strcat(string(x)," "));
+    stop = %f
+endfunction
+
+a = -5;
+b = 5;
+x0 = (a+b)/2;;
+
+// Creates the object
+opt = optimbase_new();
+
+// Configures the object
+opt = optimbase_configure(opt,"-numberofvariables",2);
+opt = optimbase_configure(opt, "-x0", x0);
+opt = optimbase_configure(opt, "-tolxrelative", 10*%eps);
+opt = optimbase_configure(opt, "-maxiter", 100);
+opt = optimbase_configure(opt, "-function", fun);
+opt = optimbase_configure(opt,"-outputcommand", myoutputcmd);
+
+function x = Dicho(opt,a,b)
+    xk = optimbase_cget(opt, "-x0");
+    [opt, fx0,index] = optimbase_function (opt , xk , 4);
+    opt = optimbase_set ( opt , "-fx0" , fx0 );
+    opt = optimbase_set ( opt , "-xopt" , x0 );
+    opt = optimbase_set ( opt , "-fopt" , fx0 );
+
+    // OutputCmd
+    brutedata = optimbase_outstruct ( opt );
+    data = tlist(["T_OPTBDATA",...
+    "x","fval","iteration","funccount"]);
+    data.x = brutedata.x;
+    data.fval = brutedata.fval;
+    data.iteration = brutedata.iteration;
+    data.funccount = brutedata.funccount;
+    stop = optimbase_outputcmd (opt , "init" , data );
+
+
+    while optimbase_get(opt, "-iterations") <optimbase_cget(opt, "-maxiter")
+        [opt, f,index] = optimbase_function(opt, xk, 4);
+        [opt, g, index] = optimbase_function(opt, a, 4);
+        if g*f <=0 then
+           b = xk;
+        else
+            a = xk;
+        end
+        x = (a+b)/2;
+        opt = optimbase_incriter(opt);
+        opt = optimbase_set ( opt , "-xopt" , x );
+        opt = optimbase_set ( opt , "-fopt" , f );
+        temp = abs(x-xk);
+        
+        if temp < optimbase_cget(opt, "-tolxrelative")
+            // OutputCmd
+            brutedata = optimbase_outstruct ( opt );
+            data = tlist(["T_OPTBDATA",...
+            "x","fval","iteration","funccount"]);
+            data.x = brutedata.x;
+            data.fval = brutedata.fval;
+            data.iteration = brutedata.iteration;
+            data.funccount = brutedata.funccount;
+            stop = optimbase_outputcmd (opt , "done" , data );
+            break
+        end
+        xk = x;
+        
+        // OutputCmd
+        brutedata = optimbase_outstruct ( opt );
+        data = tlist(["T_OPTBDATA",...
+        "x","fval","iteration","funccount"]);
+        data.x = brutedata.x;
+        data.fval = brutedata.fval;
+        data.iteration = brutedata.iteration;
+        data.funccount = brutedata.funccount;
+        stop = optimbase_outputcmd (opt , "iter" , data );
+    end
+
+endfunction
+x = Dicho(opt,a,b)
+]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_outputcmd">optimbase_outputcmd</link>
+            </member>
+            <member>
+                <link linkend="optimbase_function">optimbase_function</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_overview.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_overview.xml
new file mode 100644 (file)
index 0000000..f4c422d
--- /dev/null
@@ -0,0 +1,215 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_overview" xml:lang="en">
+    <refnamediv>
+        <refname>overview</refname>
+        <refpurpose>An overview of the Optimbase toolbox.</refpurpose>
+    </refnamediv>
+    <refsection>
+        <title>Purpose</title>
+        <para>
+            The goal of this component is to provide a building block for optimization methods.
+            The goal is to provide a building block for a large class of specialized optimization 
+            methods. This component manages
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>the number of variables,</para>
+            </listitem>
+            <listitem>
+                <para>the minimum and maximum bounds,</para>
+            </listitem>
+            <listitem>
+                <para>the number of non linear inequality constraints,</para>
+            </listitem>
+            <listitem>
+                <para>the cost function,</para>
+            </listitem>
+            <listitem>
+                <para>the logging system,</para>
+            </listitem>
+            <listitem>
+                <para>various termination criteria,</para>
+            </listitem>
+            <listitem>
+                <para>etc...</para>
+            </listitem>
+        </itemizedlist>
+        <para>
+            This toolboxes is designed with Oriented Object ideas in mind.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Features</title>
+        <para>
+            The following is a list of features the Optimbase tollbox currently provides:
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>Manage cost function</para>
+                <itemizedlist>
+                    <listitem>
+                        <para>optionnal additional argument,</para>
+                    </listitem>
+                    <listitem>
+                        <para>direct communication of the task to perform: cost function or inequality 
+                            constraints.
+                        </para>
+                    </listitem>
+                </itemizedlist>
+            </listitem>
+            <listitem>
+                <para>Manage various termination criteria, including</para>
+                <itemizedlist>
+                    <listitem>
+                        <para>maximum number of iterations,</para>
+                    </listitem>
+                    <listitem>
+                        <para>tolerance on function value (relative or absolute),</para>
+                    </listitem>
+                    <listitem>
+                        <para>tolerance on x (relative or absolute),</para>
+                    </listitem>
+                    <listitem>
+                        <para>maximum number of evaluations of cost function.</para>
+                    </listitem>
+                </itemizedlist>
+            </listitem>
+            <listitem>
+                <para>Manage the history of the convergence, including</para>
+                <itemizedlist>
+                    <listitem>
+                        <para>history of function values,</para>
+                    </listitem>
+                    <listitem>
+                        <para>history of optimim point.</para>
+                    </listitem>
+                </itemizedlist>
+            </listitem>
+            <listitem>
+                <para>Provide query features for</para>
+                <itemizedlist>
+                    <listitem>
+                        <para>the status of the optimization process,</para>
+                    </listitem>
+                    <listitem>
+                        <para>the number of iterations,</para>
+                    </listitem>
+                    <listitem>
+                        <para>the number of function evaluations,</para>
+                        <listitem>
+                            <para>function value at initial point,</para>
+                        </listitem>
+                        <listitem>
+                            <para>function value at optimal point,</para>
+                        </listitem>
+                        <listitem>
+                            <para>the optimum parameters,</para>
+                        </listitem>
+                    </listitem>
+                    <listitem>
+                        <para>etc...</para>
+                    </listitem>
+                </itemizedlist>
+            </listitem>
+        </itemizedlist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>This set of commands allows to manage an abstract optimization
+            method. The goal is to provide a building block for a large class of
+            specialized optimization methods. This component manages the number of
+            variables, the minimum and maximum bounds, the number of non linear
+            inequality constraints, the logging system, various termination criteria,
+            the cost function, etc...
+        </para>
+        <para>The optimization problem to solve is the following</para>
+        <programlisting role="no-scilab-exec">
+            min f(x)
+            l_i &lt;= x_i &lt;= h_i, i = 1,n
+            g_i(x) &gt;= 0, i = 1,nbineq
+        </programlisting>
+        <para>where</para>
+        <variablelist>
+            <varlistentry>
+                <term>n</term>
+                <listitem>
+                    <para>number of variables</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>nbineq</term>
+                <listitem>
+                    <para>number of inequality constraints</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <para>
+            In the following example, ones searches to solve f(x) = 0 thanks dichotomy method.
+            An optimization object is created and configured (number of variables, initial point, 
+            maximum number of iterations, ...). The <literal>-verbose</literal> option is enabled so that 
+            messages are generated during the algorithm, are printed.
+        </para>
+        <programlisting role="example">
+            <![CDATA[ 
+    function [f, index] = fun(x, index)
+        f = 2*x - 4;
+    endfunction
+
+    a = -5;
+    b = 5;
+    x0 = (a+b)/2;
+
+    // Creation of the object
+    opt = optimbase_new();
+
+    // Configures the object
+    opt = optimbase_configure(opt,"-numberofvariables",2);
+    opt = optimbase_configure(opt, "-x0", x0);
+    opt = optimbase_configure(opt, "-tolxrelative", 10*%eps);
+    opt = optimbase_configure(opt, "-maxiter", 30);
+    opt = optimbase_configure(opt, "-function", fun);
+    opt = optimbase_configure(opt,"-verbose",1);
+
+
+    function x = Dicho(opt,a, b)
+        xk = optimbase_cget(opt, "-x0");
+        [opt, fx0, index] = optimbase_function (opt , xk , 1);
+        opt = optimbase_set ( opt , "-xopt" , xk );
+        opt = optimbase_set ( opt , "-fopt" , fx0 );
+        terminate = %f;
+        while ~terminate
+            [opt, f, index] = optimbase_function(opt, xk, 1);
+            [opt, g, index] = optimbase_function(opt, a, 1);
+            if g*f <= 0 then
+                b = xk;
+            else
+                a = xk;
+            end
+            x = (a + b)/2;
+            opt = optimbase_incriter(opt);
+            [opt, terminate, status] = optimbase_terminate(opt, optimbase_get(opt, "-fopt"), f, xk, x);
+            opt = optimbase_set ( opt , "-xopt" , x );
+            opt = optimbase_set ( opt , "-fopt" , f );
+            xk = x;
+        end
+endfunction
+
+x = Dicho(opt,a,b)
+ ]]>
+        </programlisting>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_proj2bnds.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_proj2bnds.xml
new file mode 100644 (file)
index 0000000..e82ee76
--- /dev/null
@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_proj2bnds" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_proj2bnds</refname>
+        <refpurpose>Returns a projection point.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            [opt, p] = optimbase_proj2bnds(opt, x)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>x </term>
+                <listitem>
+                    <para>A vector of doubles, the current point.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>p </term>
+                <listitem>
+                    <para>A vector of doubles, the projected point.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_proj2bnds</literal> function returns a point, which is the 
+            projection of the given point into the bounds.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new ();
+    opt = optimbase_configure(opt,"-numberofvariables",2);
+    opt = optimbase_configure(opt,"-verbose",1);
+    opt = optimbase_configure ( opt , "-boundsmin" , [-5.0 -5.0] );
+    opt = optimbase_configure ( opt , "-boundsmax" , [5.0 5.0] );
+    [ opt , p ] = optimbase_proj2bnds ( opt ,  [0.0 0.0] );
+    disp(p)
+
+    [ opt , p ] = optimbase_proj2bnds ( opt ,  [-6.0 6.0] );
+    disp(p)
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_checkx0">optimbase_checkx0</link>
+            </member>
+            <member>
+                <link linkend="optimbase_checkbounds">optimbase_checkbounds</link>
+            </member>
+            <member>
+                <link linkend="optimbase_hasbounds">optimbase_hasbounds </link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_set.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_set.xml
new file mode 100644 (file)
index 0000000..d742367
--- /dev/null
@@ -0,0 +1,154 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_set" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_set</refname>
+        <refpurpose>Set the value for the given key.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_set(opt, key, value)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>key </term>
+                <listitem>
+                    <para>A string corresponding to name of the key to set.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>value </term>
+                <listitem>
+                    <para>the value in fonction of the given key.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_set</literal> function set the value for the given key. 
+            If the key is unknown, this function generates an error.
+        </para>
+        <para>
+            The following keys are available:
+        </para>
+        <variablelist>
+            <varlistentry>
+                <term>-funevals </term>
+                <listitem>
+                    <para>The number of function evaluations is a 1-by-1 matrix of doubles, 
+                        positive, integer value.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-iterations </term>
+                <listitem>
+                    <para>The number of iterations is a 1-by-1 matrix of doubles, positive, 
+                        integer value.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-xopt </term>
+                <listitem>
+                    <para>The x optimum.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-fopt </term>
+                <listitem>
+                    <para>The optimum cost function value.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-historyxopt </term>
+                <listitem>
+                    <para>An array, with nbiter values, containing the history of x during the 
+                        iterations.
+                    </para>
+                    <para>This array is available after optimization if the history storing was 
+                        enabled with the <literal>-storehistory</literal> option.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-historyfopt </term>
+                <listitem>
+                    <para>An array, with nbiter values, containing the history of the function value 
+                        during the iterations.
+                    </para>
+                    <para>This array is available after optimization if the history storing was 
+                        enabled with the <literal>-storehistory</literal> option.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-fx0 </term>
+                <listitem>
+                    <para>The function value for the initial guess.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>-status </term>
+                <listitem>
+                    <para>A string containing the status of the optimization.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new();
+
+    // Set optimum
+    opt = optimbase_set(opt,"-xopt",[1.0 1.0]) ;
+    val = optimbase_get(opt, "-xopt")
+    // Set function value at optimum
+
+    opt = optimbase_set(opt,"-fopt",1.0);
+    val = optimbase_get(opt, "-fopt")
+
+    // Set status
+    opt = optimbase_set(opt,"-status","maxiter");;
+    val = optimbase_get(opt, "-status")
+
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_histset">optimbase_histset</link>
+            </member>
+            <member>
+                <link linkend="optimbase_get">optimbase_get</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_stoplog.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_stoplog.xml
new file mode 100644 (file)
index 0000000..d20b845
--- /dev/null
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_stoplog" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_stoplog</refname>
+        <refpurpose>Prints the given stopping message.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            opt = optimbase_stoplog(opt, msg)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>msg </term>
+                <listitem>
+                    <para>A string, the message to print.</para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_stoplog</literal> function prints the given stopping rule message 
+            if verbose termination option is enabled. If verbose termination option is disabled, 
+            does nothing.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <programlisting role="example">
+            <![CDATA[ 
+    opt = optimbase_new ();
+    opt = optimbase_configure(opt,"-numberofvariables",2);
+    opt = optimbase_configure(opt,"-verbose",1);
+    opt = optimbase_configure ( opt , "-verbosetermination" , 1 );
+    opt = optimbase_stoplog ( opt , "My message is stopping." );
+    opt = optimbase_destroy(opt);
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_log">optimbase_log</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/optimization/help/en_US/optimbase/optimbase_terminate.xml b/scilab/modules/optimization/help/en_US/optimbase/optimbase_terminate.xml
new file mode 100644 (file)
index 0000000..31541d5
--- /dev/null
@@ -0,0 +1,307 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Adeline CARNIS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<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="optimbase_terminate" xml:lang="en">
+    <refnamediv>
+        <refname>optimbase_terminate</refname>
+        <refpurpose>Checks if the algorithm is terminated.</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Calling Sequence</title>
+        <synopsis>
+            [opt, terminate, status] = optimbase_terminate(opt, previousfopt, currentfopt, previousxopt, currentxopt)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Argument</title>
+        <variablelist>
+            <varlistentry>
+                <term>opt </term>
+                <listitem>
+                    <para>The object of TOPTIM type (tlist).</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>previousfopt </term>
+                <listitem>
+                    <para>A vector of doubles, the previous value of the cost function.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>currentfopt </term>
+                <listitem>
+                    <para>A vector of doubles, the current value of the cost function.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>previousxopt </term>
+                <listitem>
+                    <para>A vector of doubles, the previous x optimum.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>currentxopt </term>
+                <listitem>
+                    <para>A vector of doubles, the current x optimum.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>terminate </term>
+                <listitem>
+                    <para>A boolean.</para>
+                    <para>terminate = %t if the algorithm must terminate.</para>
+                    <para>terminate = %f if the algorithme must continue.</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>status </term>
+                <listitem>
+                    <para>A string.</para>
+                    <para>
+                        If <literal>terminate</literal> = %t, the detailed status of the termination 
+                        corresponds to :
+                    </para>
+                    <variablelist>
+                        <varlistentry>
+                            <term>"maxiter"</term>
+                            <listitem>
+                                The maximum number of iterations, provided by the 
+                                <literal>-maxiter</literal> option, is reached.
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term>"maxfuneval"</term>
+                            <listitem>
+                                The maximum number of function evaluations, provided by the 
+                                <literal>-maxfunevals</literal> option, is reached.
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term>"tolf"</term>
+                            <listitem>
+                                The tolerance on the function value is reached. This status is associated 
+                                with the <literal>-tolfunmethod</literal>, <literal>-tolfunabsolute</literal> 
+                                and <literal>-tolfunrelative</literal> options.
+                            </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                            <term>"tolx"</term>
+                            <listitem>
+                                The tolerance on x is reached. This status is associated with the 
+                                <literal>-tolxmethod</literal>, <literal>-tolxabsolute</literal> and 
+                                <literal>-tolxrelative</literal> options.
+                            </listitem>
+                        </varlistentry>
+                    </variablelist>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            The <literal>optimbase_terminate</literal> function returns a boolean: 
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    %t if the algorithm is terminated,
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    %f if the algorithm must continue.
+                </para>
+            </listitem>
+        </itemizedlist>
+        <para>
+            If the <literal>-verbosetermination</literal> option is enabled, messages are printed 
+            detailing the termination intermediate steps. 
+        </para>
+        <para>
+            The <literal>optimbase_terminate</literal> function uses a set of rules to compute if 
+            the termination occurs, which leads to an optimization status which is equal to one of 
+            the following: "continue", "maxiter", "maxfunevals", "tolf", "tolx". The set of rules 
+            is the following.
+        </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    By default, the status is "continue", and the terminate flag is %f.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    The number of iterations is examined and compared to the <literal>-maxiter</literal> 
+                    option. If the following condition 
+                </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                   iterations &gt;= maxiter
+                ]]>
+                </programlisting>
+                <para>
+                    is true, then the status is set to "maxiter" and terminate is set to %t.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    The number of function evaluations and compared to the <literal>-maxfunevals</literal> 
+                    option is examined. I the following condition
+                </para>
+                <programlisting role="no-scilab-exec">
+                    <![CDATA[ 
+                   funevals &gt;= maxfunevals
+                ]]>
+                </programlisting>
+                <para>
+                    is true, then the status is set to "maxfunevals" and terminate is set to %t.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    The tolerance on function value is examined depending on the value of the 
+                    <literal>-tolfunmethod</literal> option.
+                </para>
+                <variablelist>
+                    <varlistentry>
+                        <term>"disabled" </term>
+                        <listitem>
+                            <para>then the tolerance on f is just skipped.</para>
+                        </listitem>
+                        <term>"enabled" </term>
+                        <listitem>
+                            <para>if the following condition</para>
+                            <programlisting role="no-scilab-exec">
+                                <![CDATA[ 
+                   abs(currentfopt) &lg; tolfunrelative * abs(previousfopt) + tolfunabsolute
+                ]]>
+                            </programlisting>
+                            <para>
+                                is true, then the status is set to "tolf" and terminate is set to %t.
+                            </para>
+                        </listitem>
+                    </varlistentry>
+                </variablelist>
+                <para>
+                    The relative termination criteria on the function value works well if the function 
+                    value at optimum is near zero. In that case, the function value at initial guess 
+                    <literal>fx0</literal> may be used as previousfopt.
+                </para>
+                <para>
+                    The absolute termination criteria on the function value works if the user has an 
+                    accurate idea of the optimum function value.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    The tolerance on <literal>x</literal> is examined depending on the value of the 
+                    <literal>-tolxmethod</literal> otpion.
+                </para>
+                <variablelist>
+                    <varlistentry>
+                        <term>%f </term>
+                        <listitem>
+                            <para>then the tolerance on x is just skipped.</para>
+                        </listitem>
+                        <term>%t </term>
+                        <listitem>
+                            <para>if the following condition</para>
+                            <programlisting role="no-scilab-exec">
+                                <![CDATA[ 
+                   norm(currentxopt - previousxopt) &lg; tolxrelative * norm(currentxopt) + tolxabsolute
+                ]]>
+                            </programlisting>
+                            <para>
+                                is true, then the status is set to "tolx" and terminate is set to %t.
+                            </para>
+                        </listitem>
+                    </varlistentry>
+                </variablelist>
+                <para>
+                    The relative termination criteria on x works well if x at optimum is different 
+                    form zero. In that case, the condition measures the distance between two iterates.
+                </para>
+                <para>
+                    The absolute termination criteria on x works if the user has an accurate idea of 
+                    the scale of the optimum x. If the optimum x is nea 0, the relative tolerance 
+                    will not work and the absolute tolerance is more appropriate.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </refsection>
+    <refsection>
+        <title>Example</title>
+        <para>
+            In the following example, ones searches to solve f(x) = 0 thanks dichotomy method.
+            An optimization object is created and configured (number of variables, initial point, 
+            maximum number of iterations, ...). The <literal>-verbose</literal> option is enabled so that 
+            messages are generated during the algorithm, are printed.
+        </para>
+        <programlisting role="example">
+            <![CDATA[ 
+    function [f, index] = fun(x, index)
+        f = 2*x - 4;
+    endfunction
+
+    a = -5;
+    b = 5;
+    x0 = (a+b)/2;
+
+    // Creation of the object
+    opt = optimbase_new();
+
+    // Configures the object
+    opt = optimbase_configure(opt,"-numberofvariables",2);
+    opt = optimbase_configure(opt, "-x0", x0);
+    opt = optimbase_configure(opt, "-tolxrelative", 10*%eps);
+    opt = optimbase_configure(opt, "-maxiter", 30);
+    opt = optimbase_configure(opt, "-function", fun);
+    opt = optimbase_configure(opt,"-verbose",1);
+
+
+    function x = Dicho(opt,a, b)
+        xk = optimbase_cget(opt, "-x0");
+        [opt, fx0, index] = optimbase_function (opt , xk , 1);
+        opt = optimbase_set ( opt , "-xopt" , xk );
+        opt = optimbase_set ( opt , "-fopt" , fx0 );
+        terminate = %f;
+        while ~terminate
+            [opt, f, index] = optimbase_function(opt, xk, 1);
+            [opt, g, index] = optimbase_function(opt, a, 1);
+            if g*f <= 0 then
+                b = xk;
+            else
+                a = xk;
+            end
+            x = (a + b)/2;
+            opt = optimbase_incriter(opt);
+            [opt, terminate, status] = optimbase_terminate(opt, optimbase_get(opt, "-fopt"), f, xk, x);
+            opt = optimbase_set ( opt , "-xopt" , x );
+            opt = optimbase_set ( opt , "-fopt" , f );
+            xk = x;
+        end
+endfunction
+
+x = Dicho(opt,a,b)
+ ]]>
+        </programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="optimbase_function">optimbase_function</link>
+            </member>
+        </simplelist>
+    </refsection>
+</refentry>