path: root/help/en_US/intfminbnd.xml

<?xml version="1.0" encoding="UTF-8"?>

<!--
 *
 * This help file was generated from intfminbnd.sci using help_from_sci().
 *
 -->

<refentry version="5.0-subset Scilab" xml:id="intfminbnd" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:ns3="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:scilab="http://www.scilab.org"
          xmlns:db="http://docbook.org/ns/docbook">

  <refnamediv>
    <refname>intfminbnd</refname>
    <refpurpose>Solves a multi-variable optimization problem on a bounded interval</refpurpose>
  </refnamediv>


<refsynopsisdiv>
   <title>Calling Sequence</title>
   <synopsis>
   xopt = intfminbnd(f,intcon,x1,x2)
   xopt = intfminbnd(f,intcon,x1,x2,options)
   [xopt,fopt] = intfminbnd(.....)
   [xopt,fopt,exitflag]= intfminbnd(.....)
   [xopt,fopt,exitflag,output]=intfminbnd(.....)
   [xopt,fopt,exitflag,gradient,hessian]=intfminbnd(.....)
   
   </synopsis>
</refsynopsisdiv>

<refsection>
   <title>Input Parameters</title>
   <variablelist>
   <varlistentry><term>f :</term>
      <listitem><para> A function, representing the objective function of the problem.</para></listitem></varlistentry>
    <varlistentry><term><latex>x_{1}</latex> :</term>
      <listitem><para> A vector, containing the lower bound of the variables of size (1 X n) or (n X 1) where n is number of variables. If it is empty it means that the lower bound is <latex>-\infty</latex>.</para></listitem></varlistentry>
   <varlistentry><term><latex>x_{2}</latex> :</term>
      <listitem><para> A vector, containing the upper bound of the variables of size (1 X n) or (n X 1) or (0 X 0) where n is the number of variables. If it is empty it means that the upper bound is <latex>\infty</latex>.</para></listitem></varlistentry>
   <varlistentry><term>intcon :</term>
      <listitem><para> A vector of integers, representing the variables that are constrained to be integers.</para></listitem></varlistentry>
   <varlistentry><term>options :</term>
      <listitem><para> A list, containing the options for user to specify. See below for details.</para></listitem></varlistentry>
      </variablelist>
</refsection>
      <refsection>
<title> Outputs</title>
 <variablelist>
   <varlistentry><term>xopt :</term>
      <listitem><para> A vector of doubles, containing the computed solution of the optimization problem.</para></listitem></varlistentry>
   <varlistentry><term>fopt :</term>
      <listitem><para> A double, containing the the function value at x.</para></listitem></varlistentry>
   <varlistentry><term>exitflag :</term>
      <listitem><para> An integer, containing the flag which denotes the reason for termination of algorithm. See below for details.</para></listitem></varlistentry>
   <varlistentry><term>gradient :</term>
      <listitem><para> A vector of doubles, containing the objective's gradient of the solution.</para></listitem></varlistentry>
   <varlistentry><term>hessian  :</term>
      <listitem><para>A matrix of doubles, containing the Lagrangian's hessian of the solution.</para></listitem></varlistentry>
   </variablelist>
</refsection>

<refsection>
   <title>Description</title>
   <para>
Search the minimum of a multi-variable function on bounded interval specified by :
Find the minimum of f(x) such that
   </para>
   <para>
<latex>
\begin{eqnarray}
&amp;\mbox{min}_{x}
&amp; f(x)\\
&amp; \text{Subjected to:}\\ &amp; x_{1} \ &lt; x \ &lt; x_{2} \\
\end{eqnarray}
</latex>
   </para>
   <para>
intfminbnd calls Bonmin, which is an optimization library written in C++, to solve the bound optimization problem.
   </para>
   <para>
<title>Options</title>
The options allow the user to set various parameters of the Optimization problem. The syntax for the options is given by:
   </para>
   <para>
options= list("IntegerTolerance", [---], "MaxNodes",[---], "MaxIter", [---], "AllowableGap",[---] "CpuTime", [---],"gradobj", "off", "hessian", "off" );
<itemizedlist>
<listitem>IntegerTolerance : A Scalar, a number with that value of an integer is considered integer.</listitem>
<listitem>MaxNodes : A Scalar, containing the maximum number of nodes that the solver should search.</listitem>
<listitem>CpuTime : A scalar, specifying the maximum amount of CPU Time in seconds that the solver should take.</listitem>
<listitem>AllowableGap : A scalar, that specifies the gap between the computed solution and the the objective value of the best known solution stop, at which the tree search can be stopped.</listitem>
<listitem>MaxIter : A scalar, specifying the maximum number of iterations that the solver should take.</listitem>
<listitem>gradobj : A string, to turn on or off the user supplied objective gradient.</listitem>
<listitem>hessian : A scalar, to turn on or off the user supplied objective hessian.</listitem>
</itemizedlist>
   The default values for the various items are given as:
   </para>
   <para>
  options = list('integertolerance',1d-06,'maxnodes',2147483647,'cputime',1d10,'allowablegap',0,'maxiter',2147483647,'gradobj',"off",'hessian',"off")
   </para>

   <para>
The exitflag allows the user to know the status of the optimization which is returned by Bonmin. The values it can take and what they indicate is described below:
<itemizedlist>
<listitem> 0 : Optimal Solution Found </listitem>
<listitem> 1 : Maximum Number of Iterations Exceeded. Output may not be optimal.</listitem>
<listitem> 2 : Maximum amount of CPU Time exceeded. Output may not be optimal.</listitem>
<listitem> 3 : Stop at Tiny Step.</listitem>
<listitem> 4 : Solved To Acceptable Level.</listitem>
<listitem> 5 : Converged to a point of local infeasibility.</listitem>
</itemizedlist>
   </para>
   <para>
For more details on exitflag, see the Bonmin documentation which can be found on http://www.coin-or.org/Bonmin
   </para>
   <para>
</para>
</refsection>
<para>
A few examples displaying the various functionalities of intfminbnd have been provided below. You will find a series of problems and the appropriate code snippets to solve them.
   </para>
<refsection>
   <title>Example</title>
   <para>
We start with a simple objective function. Find x in R^6 such that it minimizes:
   </para>
   <para>
<latex>
\begin{eqnarray}
\mbox{min}_{x}\ f(x) = sin(x_{1}) + sin(x_{2}) + sin(x_{3}) + sin(x_{4}) + sin(x_{5}) + sin(x_{6})
\end{eqnarray}
\\\text{Subjected to:}\\
\begin{eqnarray}
\hspace{70pt} &amp;-2  &amp;\leq x{1},  x{2},  x{3},  x{4},  x{5},  x{6}  &amp;\leq 2\\
\end{eqnarray}\\
\text{With integer constraints as: }\\
\begin{eqnarray}
\begin{array}{ccc}
[2 &amp; 3 &amp; 4] \\
\end{array}
\end{eqnarray}
</latex>
   </para>
<para>
</para>
   <programlisting role="example"><![CDATA[
//Example 1:
//Objective function to be minimised
function y=f(x)
y=0
for i =1:6
y=y+sin(x(i));
end
endfunction
//Variable bounds
x1 = [-2, -2, -2, -2, -2, -2];
x2 = [2, 2, 2, 2, 2, 2];
intcon = [2 3 4]
[x,fval] =intfminbnd(f ,intcon, x1, x2)
// Press ENTER to continue

   ]]></programlisting>
</refsection>

<refsection>
   <title>Example</title>
   Here we solve a bounded objective function in R^6. We use this function to illustrate how we can further enhance the functionality of fminbnd by setting input options. We can pre-define the gradient of the objective function and/or the hessian of the lagrange function and thereby improve the speed of computation. This is elaborated on in example 2. We also set solver parameters using the options.
   <programlisting role="example"><![CDATA[
//Example 2:
//Objective function to be minimised
function y=f(x)
y=0
for i =1:6
y=y+sin(x(i));
end
endfunction
//Variable bounds
x1 = [-2, -2, -2, -2, -2, -2];
x2 = [2, 2, 2, 2, 2, 2];
intcon = [2 3 4]
//Options
options=list("MaxIter",[1500],"CpuTime", [100])
[x,fval] =intfminbnd(f ,intcon, x1, x2, options)
// Press ENTER to continue

   ]]></programlisting>
</refsection>


<refsection>
   <title>Example</title>
   <para>
    Unbounded Problems: Find x in R^2 such that it minimizes:
   </para>
   <para>
    <latex>
   \begin{eqnarray}
f(x) = -((x_{1}-1)^{2}+(x_{2}-1)^{2})
\end{eqnarray}
\\\text{Subjected to:}\\
\begin{eqnarray}
-\infty &amp;\leq x_{1} &amp;\leq \infty\\
-\infty &amp;\leq x_{2} &amp;\leq \infty
\end{eqnarray}\\
\text{With integer constraints as: } \\
\begin{eqnarray}
\begin{array}{cccccc}
[1 &amp; 2] \\
\end{array}
\end{eqnarray}
</latex>
</para>
<para>
</para>
   <programlisting role="example"><![CDATA[
///Example 3: Unbounded problem:
//Objective function to be minimised
function y=f(x)
y=-((x(1)-1)^2+(x(2)-1)^2);
endfunction
//Variable bounds
x1 = [-%inf , -%inf];
x2 = [ %inf , %inf];
//Options
options=list("MaxIter",[1500],"CpuTime", [100]);
intcon = [1 2];
[x,fval,exitflag,output,lambda] =intfminbnd(f,intcon, x1, x2, options)
   ]]></programlisting>
</refsection>

<refsection>
   <title>Authors</title>
   <simplelist type="vert">
   <member>Harpreet Singh</member>
   </simplelist>
</refsection>
</refentry>