+++ /dev/null
-<?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 <= x_i <= h_i, i = 1,n
- g_i(x) >= 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 > 0: everything is fine,</para>
- </listitem>
- <listitem>
- <para>index = 0: the optimization must stop,</para>
- </listitem>
- <listitem>
- <para>index < 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 >= 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 >= 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) < 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) < 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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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 > 0: everything is fine.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ index = 0: the optimization must stop.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ index < 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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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 <= x_i <= h_i, i = 1,n
+ g_i(x) >= 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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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>
--- /dev/null
+<?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 >= 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 >= 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) ≶ 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) ≶ 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>
projects / scilab.git / commitdiff