@c English version: 2011-06-11
@menu
* Introducción a cobyla::
* Funciones y variables para cobyla::
* Ejemplos para cobyla::  
@end menu

@node Introducción a cobyla, Funciones y variables para cobyla,  cobyla, cobyla
@section Introducción a cobyla

@code{fmin_cobyla} es una traducción a Common Lisp hecha con el
programa @code{f2cl} de la rutina Fortran COBYLA, (Powell, [1][2][3]), 
para optimización con restricciones.

COBYLA minimiza una función objetivo F(X) sujeta a M restricciones con
desigualdades de la forma g(X) >= 0 sobre X, siendo X un vector de variables
de N componentes.

Las restricciones en forma de igualdades se pueden implementar por pares
de desigualdades de la forma g(X)>=0 y -g(X)>= 0. El interfaz Maxima para
COBYLA admite restricciones de igualdad, transformándolas luego
internamente a pares de desigualdades.

El algoritmo hace uso de aproximaciones lineales, tanto de la función
objetivo como de las funciones de restricción; tales aproximaciones
se hacen mediante interpolación lineal de N+1 puntos en el espacio de
variables. Los puntos de interpolación se consideran vértices de un
simplejo o símplex. El parámetro RHO controla el tamaño
del simplejo y se reduce automáticamente de RHOBEG a RHOEND. Para cada
RHO la subrutina intenta alcanzar un buen vector de variables para el
tamaño actual, reduciéndose entonces RHO hasta alcanzar el valor de
RHOEND. Por eso, tanto a RHOBEG como a RHOEND se les deben asignar valores
razonables, lo que requiere cierto trabajo empírico previo.
La rutina trata cada restricción individualmente cuando se calcula un
en las variables. El nombre de la rutina se deriva de la frase 
@i{Constrained Optimization BY Linear Approximations}.

Referecias:

[1] Código Fortran procede de @url{http://plato.asu.edu/sub/nlores.html#general}

[2] M. J. D. Powell, "A direct search optimization method that models the objective and constraint functions by linear interpolation," en Advances in Optimization and Numerical Analysis, eds. S. Gomez and J.-P. Hennart (Kluwer Academic: Dordrecht, 1994), p. 51-67. 

[3] M. J. D. Powell, "Direct search algorithms for optimization calculations," Acta Numerica 7, 287-336 (1998).  Also available as University of Cambridge, Department of Applied Mathematics and Theoretical Physics,  Numerical Analysis Group, Report NA1998/04 from @url{https://web.archive.org/web/20160607190705/http://www.damtp.cam.ac.uk:80/user/na/reports.html}

@node Funciones y variables para cobyla, Ejemplos para cobyla, Introducción a cobyla, cobyla
@section Funciones y variables para cobyla

@deffn {Función} fmin_cobyla (@var{F}, @var{X}, @var{Y})
@deffnx {Función} fmin_cobyla (@var{F}, @var{X}, @var{Y}, optional_args)

Devuelve una aproximación del valor mínimo de la expresión
@var{F} respecto de las variables @var{X}, sujeta a un conjunto opcional
de restricciones. @var{Y} es una lista que contiene una solución semilla
inicial en @var{X}.

@var{F} debe ser una expresión ordinaria, no valen nombres de funciones
ni expresiones lambda.

@code{optional_args} hace referencia a argumentos adicionales, que se
especifican de la forma @code{@var{symbol} = @var{value}}. Los argumentos
opcionales que se reconocen son:

@table @code
@item constraints
Lista de restricciones en forma de desigualdades e igualdades que debe
satisfacer @var{X}. Las desigualdades deben ser de la forma 
@code{g(@var{X}) >= h(@var{X})} o @code{g(@var{X}) <= h(@var{X})}.
Las restricciones de igualdad deben ser de la forma 
@code{g(@var{X}) = h(@var{X})}.
@item rhobeg
Valor inicial de la variable interna RHO, que controla el tamaño del
simplejo. Su valor por defecto es 1.0.
@item rhoend 
El valor final deseado para el parámetro RHO. Es aproximadamente la
precisión de las variables. Su valor por defecto es 1d-6.
@item iprint
Nivel de información de salida. Su valor por defecto es 0.
@itemize
@item
0 - Sin información de salida
@item
1 - Sumario al final de los cálculos
@item
2 - Se van mostrando los nuevos valores de RHO y SIGMA, incluyendo
 el vector de variables.
@item
3 - Como en 2, pero la información se muestra cuando se calcula F(X).
@end itemize
@item maxfun
Número máximo de evaluaciones de la función. Su valor por defecto es 1000.
@end table

El resultado devuelto es un vector:
@enumerate
@item
Los valores de las variables con las que se alcanza el valor mínimo.
Es una lista de elementos de la forma @code{@var{var} = @var{value}} para cada
una de las variables listadas en @var{X}.
@item
El valor mínimo de la función objetivo.
@item
El número de evaluaciones de la función.
@item
Código de retorno con los siguientes significados:
 @enumerate
 @item
 0 - No ha habido errores.
 @item
 1 - Alcanzado el máximo número permitido de evaluaciones de la función.
 @item
 2 - Errores de redondeo han impedido el avance del proceso.
 @end enumerate
@end enumerate

El código @code{load("fmin_cobyla")} carga en memoria esta función..

@end deffn

@deffn {Función} bf_fmin_cobyla (@var{F}, @var{X}, @var{Y})
@deffnx {Función} bf_fmin_cobyla (@var{F}, @var{X}, @var{Y}, optional_args)

Esta función es idéntica a @code{fmin_cobyla}, excepto por el hecho
de que utiliza aritmética de precisión arbitraria (bigfloat) y que el
valor por defecto de @var{rhoend} es @code{10^(fpprec/2)}. 

Véase @code{fmin_cobyla}.

El código @code{load("fmin_cobyla")} carga en memoria esta función..

@end deffn

@node Ejemplos para cobyla, , Funciones y variables para cobyla, cobyla
@section Ejemplos para cobyla

Minimizar x1*x2 bajo la condición 1-x1^2-x2^2 >= 0.  
La solución teórica es x1 = 1/sqrt(2), x2 = -1/sqrt(2).

@c ===beg===
@c load("fmin_cobyla");
@c fmin_cobyla(x1*x2, [x1, x2], [1,1], constraints = [x1^2+x2^2<=1], iprint=1);
@c ===end===
@example
(%i1) load("fmin_cobyla")$

(%i2) fmin_cobyla(x1*x2, [x1, x2], [1,1], constraints = [x1^2+x2^2<=1], iprint=1);

   Normal return from subroutine COBYLA

   NFVALS =   66   F =-5.000000E-01    MAXCV = 1.999845E-12
   X = 7.071058E-01  -7.071077E-01
(%o2) [[x1 = 0.70710584934848, x2 = - 0.7071077130248], - 0.49999999999926, 
       [[-1.999955756559757e-12],[]], 66]
@end example

Hay más ejemplos en el directorio @code{share/cobyla/ex}.



