diff options
Diffstat (limited to 'help/en_US/fminunc.xml')
| -rw-r--r-- | help/en_US/fminunc.xml | 181 |
1 files changed, 118 insertions, 63 deletions
diff --git a/help/en_US/fminunc.xml b/help/en_US/fminunc.xml index e5a46c3..30fc9eb 100644 --- a/help/en_US/fminunc.xml +++ b/help/en_US/fminunc.xml @@ -36,26 +36,31 @@ </refsynopsisdiv> <refsection> - <title>Parameters</title> + <title>Input Parameters</title> <variablelist> <varlistentry><term>f :</term> - <listitem><para> a function, representing the objective function of the problem</para></listitem></varlistentry> + <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 of variables.</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> + <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>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, the computed solution of the optimization problem.</para></listitem></varlistentry> + <listitem><para> A vector of doubles, containing the computed solution of the optimization problem.</para></listitem></varlistentry> <varlistentry><term>fopt :</term> - <listitem><para> a scalar of double, the function value at x.</para></listitem></varlistentry> + <listitem><para> A double, containing the the function value at x.</para></listitem></varlistentry> <varlistentry><term>exitflag :</term> - <listitem><para> a scalar of integer, containing the flag which denotes the reason for termination of algorithm. See below for details.</para></listitem></varlistentry> - <varlistentry><term>output :</term> - <listitem><para> a structure, containing the information about the optimization. See below for details.</para></listitem></varlistentry> + <listitem><para> An integer, containing the flag which denotes the reason for termination of algorithm. See below for details.</para></listitem></varlistentry> + <varlistentry><term>output :</term> + <listitem><para> A structure, containing the information about the optimization. See below for details.</para></listitem></varlistentry> <varlistentry><term>gradient :</term> - <listitem><para> a vector of doubles, containing the the gradient of the solution.</para></listitem></varlistentry> + <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 the hessian of the solution.</para></listitem></varlistentry> + <listitem><para> A matrix of doubles, containing the lagrangian's hessian of the solution.</para></listitem></varlistentry> </variablelist> </refsection> @@ -63,6 +68,8 @@ <title>Description</title> <para> Search the minimum of an unconstrained optimization problem specified by : +</para> + <para> Find the minimum of f(x) such that </para> <para> @@ -74,101 +81,149 @@ Find the minimum of f(x) such that </latex> </para> <para> -The routine calls Ipopt for solving the Un-constrained Optimization problem, Ipopt is a library written in C++. +Fminunc calls Ipopt which is an optimization library written in C++, to solve the unconstrained 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("MaxIter", [---], "CpuTime", [---], "GradObj", ---, "Hessian", ---, "GradCon", ---); </para> <para> -The options allows the user to set various parameters of the Optimization problem. -It should be defined as type "list" and contains the following fields. <itemizedlist> -<listitem>Syntax : options= list("MaxIter", [---], "CpuTime", [---], "Gradient", ---, "Hessian", ---);</listitem> -<listitem>MaxIter : a Scalar, containing the Maximum Number of Iteration that the solver should take.</listitem> -<listitem>CpuTime : a Scalar, containing the Maximum amount of CPU Time that the solver should take.</listitem> -<listitem>Gradient : a function, representing the gradient function of the Objective in Vector Form.</listitem> -<listitem>Hessian : a function, representing the hessian function of the Objective in Symmetric Matrix Form.</listitem> -<listitem>Default Values : options = list("MaxIter", [3000], "CpuTime", [600]);</listitem> +<listitem>MaxIter : A Scalar, specifying the Maximum Number of Iterations that the solver should take.</listitem> +<listitem>CpuTime : A Scalar, specifying the Maximum amount of CPU Time in seconds that the solver should take.</listitem> +<listitem>Gradient: A function, representing the gradient function of the objective in Vector Form.</listitem> +<listitem>Hessian : A function, representing the hessian function of the lagrange in the form of a Symmetric Matrix with input parameters as x, objective factor and lambda. Refer to Example 5 for definition of lagrangian hessian function.</listitem> </itemizedlist> +The default values for the various items are given as: </para> <para> -The exitflag allows to know the status of the optimization which is given back by Ipopt. +options = list("MaxIter", [3000], "CpuTime", [600]); + </para> + <para> +The exitflag allows the user to know the status of the optimization which is returned by Ipopt. The values it can take and what they indicate is described below: <itemizedlist> -<listitem>exitflag=0 : Optimal Solution Found </listitem> -<listitem>exitflag=1 : Maximum Number of Iterations Exceeded. Output may not be optimal.</listitem> -<listitem>exitflag=2 : Maximum CPU Time exceeded. Output may not be optimal.</listitem> -<listitem>exitflag=3 : Stop at Tiny Step.</listitem> -<listitem>exitflag=4 : Solved To Acceptable Level.</listitem> -<listitem>exitflag=5 : Converged to a point of local infeasibility.</listitem> +<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 ipopt documentation, go to http://www.coin-or.org/Ipopt/documentation/ +For more details on exitflag, see the Ipopt documentation which can be found on http://www.coin-or.org/Ipopt/documentation/ </para> <para> -The output data structure contains detailed informations about the optimization process. -It has type "struct" and contains the following fields. +The output data structure contains detailed information about the optimization process. +It is of type "struct" and contains the following fields. <itemizedlist> -<listitem>output.Iterations: The number of iterations performed during the search</listitem> -<listitem>output.Cpu_Time: The total cpu-time spend during the search</listitem> -<listitem>output.Objective_Evaluation: The number of Objective Evaluations performed during the search</listitem> -<listitem>output.Dual_Infeasibility: The Dual Infeasiblity of the final soution</listitem> -<listitem>output.Message: The output message for the problem</listitem> +<listitem>output.Iterations: The number of iterations performed.</listitem> +<listitem>output.Cpu_Time : The total cpu-time taken.</listitem> +<listitem>output.Objective_Evaluation: The number of objective evaluations performed.</listitem> +<listitem>output.Dual_Infeasibility : The Dual Infeasiblity of the final soution.</listitem> +<listitem>output.Message: The output message for the problem.</listitem> </itemizedlist> </para> <para> </para> </refsection> + <para> +A few examples displaying the various functionalities of fminunc have been provided below. You will find a series of problems and the appropriate code snippets to solve them. + </para> + <refsection> - <title>Examples</title> + <title>Example</title> +<para> +We begin with the minimization of a simple non-linear function. +</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_{2}^{2} +\end{eqnarray} +</latex> + </para> + <para> + +</para> <programlisting role="example"><![CDATA[ -//Find x in R^2 such that it minimizes the Rosenbrock function -//f = 100*(x2 - x1^2)^2 + (1-x1)^2 +//Example 1: Simple non-linear function. //Objective function to be minimised function y= f(x) -y= 100*(x(2) - x(1)^2)^2 + (1-x(1))^2; +y= x(1)^2 + x(2)^2; endfunction //Starting point -x0=[-1,2]; -//Gradient of objective function -function y= fGrad(x) -y= [-400*x(1)*x(2) + 400*x(1)^3 + 2*x(1)-2, 200*(x(2)-x(1)^2)]; -endfunction -//Hessian of Objective Function -function y= fHess(x) -y= [1200*x(1)^2- 400*x(2) + 2, -400*x(1);-400*x(1), 200 ]; -endfunction -//Options -options=list("MaxIter", [1500], "CpuTime", [500], "Gradient", fGrad, "Hessian", fHess); +x0=[2,1]; //Calling Ipopt -[xopt,fopt,exitflag,output,gradient,hessian]=fminunc(f,x0,options) +[xopt,fopt]=fminunc(f,x0) // Press ENTER to continue ]]></programlisting> </refsection> <refsection> - <title>Examples</title> + <title>Example</title> +<para> +We now look at the Rosenbrock function, a non-convex performance test problem for optimization routines. We use this example to illustrate how we can enhance the functionality of fminunc 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. +</para> + <para> +<latex> +\begin{eqnarray} +\mbox{min}_{x}\ f(x) = 100\boldsymbol{\cdot} (x_{2} - x_{1}^{2})^{2} + (1-x_{1})^{2} +\end{eqnarray} +</latex> + </para> + <para> + +</para> <programlisting role="example"><![CDATA[ -//Find x in R^2 such that the below function is minimum -//f = x1^2 + x2^2 +//Example 2: The Rosenbrock function. //Objective function to be minimised function y= f(x) -y= x(1)^2 + x(2)^2; +y= 100*(x(2) - x(1)^2)^2 + (1-x(1))^2; endfunction //Starting point -x0=[2,1]; +x0=[-1,2]; +//Gradient of objective function +function y= fGrad(x) +y= [-400*x(1)*x(2) + 400*x(1)^3 + 2*x(1)-2, 200*(x(2)-x(1)^2)]; +endfunction +//Hessian of Objective Function +function y= fHess(x) +y= [1200*x(1)^2- 400*x(2) + 2, -400*x(1);-400*x(1), 200 ]; +endfunction +//Options +options=list("MaxIter", [1500], "CpuTime", [500], "GradObj", fGrad, "Hessian", fHess); //Calling Ipopt -[xopt,fopt]=fminunc(f,x0) +[xopt,fopt,exitflag,output,gradient,hessian]=fminunc(f,x0,options) // Press ENTER to continue ]]></programlisting> </refsection> <refsection> - <title>Examples</title> + <title>Example</title> +<para> +Unbounded Problems: Find x in R^2 such that it minimizes: +</para> + <para> +<latex> +\begin{eqnarray} +f(x) = -x_{1}^{2} - x_{2}^{2} +\end{eqnarray} +</latex> + </para> + <para> + </para> <programlisting role="example"><![CDATA[ -//The below problem is an unbounded problem: -//Find x in R^2 such that the below function is minimum -//f = - x1^2 - x2^2 +//Example 3: Unbounded objective function. //Objective function to be minimised function y= f(x) y= -x(1)^2 - x(2)^2; @@ -184,7 +239,7 @@ function y= fHess(x) y= [-2,0;0,-2]; endfunction //Options -options=list("MaxIter", [1500], "CpuTime", [500], "Gradient", fGrad, "Hessian", fHess); +options=list("MaxIter", [1500], "CpuTime", [500], "GradObj", fGrad, "Hessian", fHess); //Calling Ipopt [xopt,fopt,exitflag,output,gradient,hessian]=fminunc(f,x0,options) ]]></programlisting> |