diff options
Diffstat (limited to 'help/en_US/intfmincon.xml')
| -rw-r--r-- | help/en_US/intfmincon.xml | 509 |
1 files changed, 509 insertions, 0 deletions
diff --git a/help/en_US/intfmincon.xml b/help/en_US/intfmincon.xml new file mode 100644 index 0000000..782978e --- /dev/null +++ b/help/en_US/intfmincon.xml @@ -0,0 +1,509 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- + * + * This help file was generated from intfmincon.sci using help_from_sci(). + * + --> + +<refentry version="5.0-subset Scilab" xml:id="intfmincon" 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>intfmincon</refname> + <refpurpose>Solves a constrainted multi-variable mixed integer non linear programming problem</refpurpose> + </refnamediv> + + +<refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + xopt = intfmincon(f,x0,intcon,A,b) + xopt = intfmincon(f,x0,intcon,A,b,Aeq,beq) + xopt = intfmincon(f,x0,intcon,A,b,Aeq,beq,lb,ub) + xopt = intfmincon(f,x0,intcon,A,b,Aeq,beq,lb,ub,nlc) + xopt = intfmincon(f,x0,intcon,A,b,Aeq,beq,lb,ub,nlc,options) + [xopt,fopt] = intfmincon(.....) + [xopt,fopt,exitflag]= intfmincon(.....) + [xopt,fopt,exitflag,gradient]=intfmincon(.....) + [xopt,fopt,exitflag,gradient,hessian]=intfmincon(.....) + + </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>x0 :</term> + <listitem><para> A vector of doubles, containing the starting values of variables of size (1 X n) or (n X 1) where 'n' is the number of variables.</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>A :</term> + <listitem><para> A matrix of doubles, containing the coefficients of linear inequality constraints of size (m X n) where 'm' is the number of linear inequality constraints.</para></listitem></varlistentry> + <varlistentry><term>b :</term> + <listitem><para> A vector of doubles, related to 'A' and represents the linear coefficients in the linear inequality constraints of size (m X 1).</para></listitem></varlistentry> + <varlistentry><term>Aeq :</term> + <listitem><para> A matrix of doubles, containing the coefficients of linear equality constraints of size (m1 X n) where 'm1' is the number of linear equality constraints.</para></listitem></varlistentry> + <varlistentry><term>beq :</term> + <listitem><para> A vector of double, vector of doubles, related to 'Aeq' and represents the linear coefficients in the equality constraints of size (m1 X 1).</para></listitem></varlistentry> + <varlistentry><term>lb :</term> + <listitem><para> A vector of doubles, containing the lower bounds of the variables of size (1 X n) or (n X 1) where 'n' is the number of variables.</para></listitem></varlistentry> + <varlistentry><term>ub :</term> + <listitem><para> A vector of doubles, containing the upper bounds of the variables of size (1 X n) or (n X 1) where 'n' is the number of variables.</para></listitem></varlistentry> + <varlistentry><term>nlc :</term> + <listitem><para> A function, representing the Non-linear Constraints functions(both Equality and Inequality) of the problem. It is declared in such a way that non-linear inequality constraints (c), and the non-linear equality constraints (ceq) are defined as separate single row vectors.</para></listitem></varlistentry> + <varlistentry><term>options :</term> + <listitem><para> A list, containing the option 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 the computed solution of the optimization problem.</para></listitem></varlistentry> + <varlistentry><term>fopt :</term> + <listitem><para> A double, containing the value of the function at xopt.</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 Objective's hessian of the solution.</para></listitem></varlistentry> + </variablelist> +</refsection> + +<refsection> + <title>Description</title> + <para> +Search the minimum of a mixed integer constrained optimization problem specified by : +Find the minimum of f(x) such that + </para> + <para> +<latex> +\begin{eqnarray} +&\mbox{min}_{x} +& f(x) \\ +& \text{Subjected to:} & A \boldsymbol{\cdot} x \leq b \\ +& & Aeq \boldsymbol{\cdot} x \ = beq\\ +& & c(x) \leq 0\\ +& & ceq(x) \ = 0\\ +& & lb \leq x \leq ub \\ +& & x_{i} \in \!\, \mathbb{Z}, i \in \!\, I +\end{eqnarray} +</latex> + </para> + <para> +intfmincon calls Bonmin, an optimization library written in C++, to solve the Constrained 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> + </para> + <para> +The exitflag allows to know the status of the optimization which is given back by Ipopt. +<itemizedlist> +<listitem>0 : Optimal Solution Found </listitem> +<listitem>1 : InFeasible Solution.</listitem> +<listitem>2 : Objective Function is Continuous Unbounded.</listitem> +<listitem>3 : Limit Exceeded.</listitem> +<listitem>4 : User Interrupt.</listitem> +<listitem>5 : MINLP Error.</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 intfmincon 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> + Here we solve a simple objective function, subjected to three linear inequality constraints. + </para> + <para> +Find x in R^2 such that it minimizes: + </para> + <para> +<latex> +\begin{eqnarray} +\mbox{min}_{x}\ f(x) = x_{1}^{2} - x_{1} \boldsymbol{\cdot} x_{2}/3 + x_{2}^{2} +\end{eqnarray} +\\\text{Subjected to:}\\ +\begin{eqnarray} +\hspace{70pt} &x_{1} + x_{2}&\leq 2\\ +\hspace{70pt} &x_{1} + \dfrac{x_{2}}{4}&\leq 1\\ +\hspace{70pt} &-x_{1} + x_{2}&\geq -2\\ +\end{eqnarray}\\ +\text{With integer constraints as: } \\ +\begin{eqnarray} +\begin{array}{c} +[1] \\ +\end{array} +\end{eqnarray} +</latex> + </para> + <para> + + </para> + <programlisting role="example"><![CDATA[ +//Example 1: +//Objective function to be minimised +function [y,dy]=f(x) +y=-x(1)-x(2)/3; +dy= [-1,-1/3]; +endfunction +//Starting point +x0=[0 , 0]; +//Integer constraints +intcon = [1]; +//Initializing the linear inequality constraints +A=[1,1 ; 1,1/4 ; 1,-1 ;]; +b=[2;1;2]; +//Calling Bonmin +[x,fval,exitflag,grad,hessian] =intfmincon(f, x0,intcon,A,b) +// Press ENTER to continue + + ]]></programlisting> +</refsection> + +<refsection> + <title>Example</title> + <para> +Here we build up on the previous example by adding linear equality constraints. +We add the following constraints to the problem specified above: +</para> + <para> +<latex> +\begin{eqnarray} +&x_{1} - x_{2}&= 1 +\\&2x_{1} + x_{2}&= 2 +\\\end{eqnarray} +</latex> + </para> + <para> + </para> + <programlisting role="example"><![CDATA[ +//Example 2: +//Objective function to be minimised +function [y,dy]=f(x) +y=-x(1)-x(2)/3; +dy= [-1,-1/3]; +endfunction +//Starting point +x0=[0 , 0]; +//Integer constraints +intcon = [1]; +//Initializing the linear inequality constraints +A=[1,1 ; 1,1/4 ; 1,-1 ;]; +b=[2;1;2]; +//Linear equality constraints +Aeq=[1,-1;2,1]; +beq=[1,2]; +//Calling Bonmin +[x,fval,exitflag,grad,hessian] =intfmincon(f, x0,intcon,A,b,Aeq,beq) +// Press ENTER to continue + + ]]></programlisting> +</refsection> + +<refsection> + <title>Example</title> + <para> +In this example, we proceed to add the upper and lower bounds to the objective function. + </para> + <para> +Find x in R^2 such that it minimizes: + </para> + <para> +<latex> +\begin{eqnarray} +-1 &\leq x_{1} &\leq \infty\\ +-\infty &\leq x_{2} &\leq 1 +\end{eqnarray} +</latex> + </para> + <para> + + </para> + <programlisting role="example"><![CDATA[ +//Example 3: +//Objective function to be minimised +function [y,dy]=f(x) +y=-x(1)-x(2)/3; +dy= [-1,-1/3]; +endfunction +//Starting point +x0=[0 , 0]; +//Integer constraints +intcon = [1]; +//Initializing the linear inequality constraints +A=[1,1 ; 1,1/4 ; 1,-1 ;]; +b=[2;1;2]; +//Linear equality constraints +Aeq=[1,-1;2,1]; +beq=[1,2]; +//Adding the variable bounds +lb=[-1, -%inf]; +ub=[%inf, 1]; +//Calling Bonmin +[x,fval,exitflag,grad,hessian] =intfmincon(f, x0,intcon,A,b,Aeq,beq,lb,ub) +// Press ENTER to continue + + ]]></programlisting> +</refsection> + +<refsection> + <title>Example</title> + <para> + Finally, we add the non-linear constraints to the problem. Note that there is a notable difference in the way this is done as compared to defining the linear constraints. + </para> + <para> +<latex> +\begin{eqnarray} +\mbox{min}_{x}\ f(x) = x_{1} \boldsymbol{\cdot} x_{2} + x_{2} \boldsymbol{\cdot} x_{3} +\end{eqnarray} +\\\text{Subjected to:}\\ +\begin{eqnarray} +\hspace{70pt} &x_{1}^{2} - x_{2}^{2} + x_{3}^{2}&\leq 2\\ +\hspace{70pt} &x_{1}^{2} + x_{2}^{2} + x_{3}^{2}&\leq 10\\ +\end{eqnarray}\\ +\text{With integer constraints as: }\\ +\begin{eqnarray} +\begin{array}{c} +[2] \\ +\end{array} +\end{eqnarray} +</latex> + </para> + <para> + </para> + <programlisting role="example"><![CDATA[ +//Example 4: +//Objective function to be minimised +function [y,dy]=f(x) +y=x(1)*x(2)+x(2)*x(3); +dy= [x(2),x(1)+x(3),x(2)]; +endfunction +//Starting point, linear constraints and variable bounds +x0=[0.1 , 0.1 , 0.1]; +intcon = [2] +A=[]; +b=[]; +Aeq=[]; +beq=[]; +lb=[]; +ub=[]; +//Nonlinear constraints +function [c,ceq,cg,cgeq]=nlc(x) +c = [x(1)^2 - x(2)^2 + x(3)^2 - 2 , x(1)^2 + x(2)^2 + x(3)^2 - 10]; +ceq = []; +cg=[2*x(1) , -2*x(2) , 2*x(3) ; 2*x(1) , 2*x(2) , 2*x(3)]; +cgeq=[]; +endfunction +//Options +options=list("MaxIter", [1500], "CpuTime", [500], "GradObj", "on","GradCon", "on"); +//Calling Ipopt +[x,fval,exitflag,output] =intfmincon(f, x0,intcon,A,b,Aeq,beq,lb,ub,nlc,options) +// Press ENTER to continue + + ]]></programlisting> +</refsection> + +<refsection> + <title>Example</title> + <para> +We can further enhance the functionality of intfmincon 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 5. We take the following problem and add simple non-linear constraints, specify the gradients and the hessian of the Lagrange Function. We also set solver parameters using the options. + </para> + <para> + </para> + <programlisting role="example"><![CDATA[ +//Example 5: +//Objective function to be minimised +function [y,dy]=f(x) +y=x(1)*x(2)+x(2)*x(3); +dy= [x(2),x(1)+x(3),x(2)]; +endfunction +//Starting point, linear constraints and variable bounds +x0=[0.1 , 0.1 , 0.1]; +intcon = [2] +A=[]; +b=[]; +Aeq=[]; +beq=[]; +lb=[]; +ub=[]; +//Nonlinear constraints +function [c,ceq,cg,cgeq]=nlc(x) +c = [x(1)^2 - x(2)^2 + x(3)^2 - 2 , x(1)^2 + x(2)^2 + x(3)^2 - 10]; +ceq = []; +cg=[2*x(1) , -2*x(2) , 2*x(3) ; 2*x(1) , 2*x(2) , 2*x(3)]; +cgeq=[]; +endfunction +//Options +options=list("MaxIter", [1500], "CpuTime", [500], "GradObj", "on","GradCon", "on"); +//Calling Ipopt +[x,fval,exitflag,output] =intfmincon(f, x0,intcon,A,b,Aeq,beq,lb,ub,nlc,options) +// Press ENTER to continue + + ]]></programlisting> +</refsection> + +<refsection> + <title>Example</title> + <para> +Infeasible Problems: Find x in R^3 such that it minimizes: + </para> + <para> +<latex> +\begin{eqnarray} +f(x) = x_{1} \boldsymbol{\cdot} x_{2} + x_{2} \boldsymbol{\cdot} x_{3} +\end{eqnarray} +\\\text{Subjected to:}\\ +\begin{eqnarray} +\hspace{70pt} &x_{1}^{2} &\leq 1\\ +\hspace{70pt} &x_{1}^{2} + x_{2}^{2}&\leq 1\\ +\hspace{70pt} &x_{3}^{2}&\leq 1\\ +\hspace{70pt} &x_{1}^{3}&\leq 0.5\\ +\hspace{70pt} &x_{2}^{2} + x_{3}^{2}&\leq 0.75\\ +\end{eqnarray}\\ +\text{With variable bounds as: }\\ +\begin{eqnarray} +\hspace{70pt} 0 &\leq x_{1} &\leq 0.6\\ +\hspace{70pt} 0.2 &\leq x_{2} &\leq \infty\\ +\end{eqnarray}\\ +\text{With integer constraints as: } \\ +\begin{eqnarray} +\begin{array}{c} +[2] \\ +\end{array} +\end{eqnarray} +</latex> + </para> + <para> + </para> + <programlisting role="example"><![CDATA[ +//Example 6: +//Objective function to be minimised +function [y,dy]=f(x) +y=x(1)*x(2)+x(2)*x(3); +dy= [x(2),x(1)+x(3),x(2)]; +endfunction +//Starting point, linear constraints and variable bounds +x0=[1,1,1]; +intcon = [2] +A=[]; +b=[]; +Aeq=[]; +beq=[]; +lb=[0 0.2,-%inf]; +ub=[0.6 %inf,1]; +//Nonlinear constraints +function [c,ceq,cg,cgeq]=nlc(x) +c=[x(1)^2-1,x(1)^2+x(2)^2-1,x(3)^2-1]; +ceq=[x(1)^3-0.5,x(2)^2+x(3)^2-0.75]; +cg = [2*x(1),0,0;2*x(1),2*x(2),0;0,0,2*x(3)]; +cgeq = [3*x(1)^2,0,0;0,2*x(2),2*x(3)]; +endfunction +//Options +options=list("MaxIter", [1500], "CpuTime", [500], "GradObj", "on","GradCon", "on"); +//Calling Bonmin +[x,fval,exitflag,grad,hessian] =intfmincon(f, x0,intcon,A,b,Aeq,beq,lb,ub,nlc,options) +// Press ENTER to continue + ]]></programlisting> +</refsection> + +<refsection> + <title>Example</title> +<para> +Unbounded Problems: Find x in R^3 such that it minimizes: +</para> + <para> +<latex> +\begin{eqnarray} +\mbox{min}_{x}\ f(x) = x_{1}^{2} + x_{2}^{2} + x_{3}^{2}\\ +\end{eqnarray}\\ +\text{With variable bounds as: }\\ +\begin{eqnarray} +-\infty &\leq x_{1} &\leq 0\\ +-\infty &\leq x_{2} &\leq 0\\ +-\infty &\leq x_{3} &\leq 0\\ +\end{eqnarray}\\ +\text{With integer constraints as: } \\ +\begin{eqnarray} +\begin{array}{c} +[3] \\ +\end{array} +\end{eqnarray} +</latex> + </para> + <para> + </para> + <programlisting role="example"><![CDATA[ +//Example 7: +//The below problem is an unbounded problem: +//Find x in R^3 such that it minimizes: +//f(x)= -(x1^2 + x2^2 + x3^2) +//x0=[0.1 , 0.1 , 0.1] +// x1 <= 0 +// x2 <= 0 +// x3 <= 0 +//Objective function to be minimised +function y=f(x) +y=-(x(1)^2+x(2)^2+x(3)^2); +endfunction +//Starting point, linear constraints and variable bounds +x0=[0.1 , 0.1 , 0.1]; +intcon = [3] +A=[]; +b=[]; +Aeq=[]; +beq=[]; +lb=[]; +ub=[0,0,0]; +//Options +options=list("MaxIter", [1500], "CpuTime", [500]); +//Calling Bonmin +[x,fval,exitflag,grad,hessian] =intfmincon(f, x0,intcon,A,b,Aeq,beq,lb,ub,[],options) +// Press ENTER to continue + + ]]></programlisting> +</refsection> + + +<refsection> + <title>Authors</title> + <simplelist type="vert"> + <member>Harpreet Singh</member> + </simplelist> +</refsection> +</refentry> |