****************************************************
****************************************************
**  MotorAG - Motor de Algoritmos Genticos v1.0  **
**       (u)2003, Gustavo Brown Rodriguez         **
**       e-mail: alegus@adinet.com.uy             **
****************************************************
****************************************************

Manual de ayuda de la aplicacion FunctionSolver
-----------------------------------------------

INDICE

1-......... Sobre FuncionSolverApplet
2-......... Panel de control
2.1-....... Seleccin de la funcin a maximizar
2.1.1-..... Funcin de 1 variable
2.1.2-..... Funcin de varias variables
2.1.3-..... Funciones de variables enteras y variables continuas
2.2-....... Generacin
2.3-....... Seleccin
2.4-....... Escaladores de fitness
2.5-....... Variables
2.5.1-..... Cruzamiento
2.5.2-..... Mutacin
2.5.3-..... Rango
3-......... Botones de comando
4-......... Despliegue grfico de la poblacin actual
4.1-....... Despliegue grfico para individuos de 1 sola variable
4.2-....... Despliegue grfico para individuos de varias variables
4.3-....... Manejo de Zooming, panning, etc sobre el grfico


1- Sobre FuncionSolverApplet

La aplicacin de testeo puede ejecutarse como applet desde
un browser (donde el punto de partida es la clase
com.brownsoft.ag.FunctionSolverApplet) o desde el command
prompt mediante la linea de comandos
  java -jar MotorAG.jar
Se recomienza ejecutar el programa como una aplicacin
standalone, ya que de esta manera se permite redimensionar
la ventana de la aplicacin para mejorar el despliegue
grfico del motor.
El applet permite utilizar algoritmos genticos para
resolver problemas de maximizacin/minimizacin de
funciones de una o varias variables.
En el funcionamiento normal de la aplicacin, el fitness
de los individuos equivale a la evaluacin de la funcin
objetivo con el material gentico de los mismos.
Para transformar el problema de maximizacin en uno de
minimizacin referirse a la seccin de FitnessScalers de
este mismo documento.

La aplicacion divide la pantalla en 3 zonas. La franja
superior (no siempre visible) es donde se muestra la ayuda
del programa (este texto).
La franja inferior es donde se encuentra el panel de control
Alli se selecciona la funcion a maximizar y se elijen los
operadores geneticos a utilizar y sus parmetros.
Por ltimo, la franja central es donde se despliega
grficamente la poblacion actual del motor.


2- Panel de control

Desde el panel de control se puede customizar practicamente
la totalidad de los parametros que presenta el motor de
algortmos genticos.
La configuracion inicial de las funciones pregrabadas y sus
respectivas configuraciones se encuentran en el archivo
'funciones.ini' y pueden ser editadas manualmente por
cualquier editor de texto.
A la izquierda del panel se encuentra un listbox con la
lista de funciones disponibles.
Una vez seleccionada una funcion podemos ver al centro un
nuevo listbox con los distintos parametros de que dispone el
motor para esta funcion.
Los parametros actualmente disponibles son 'Generacion',
'Seleccion', 'FitnessScaler' y una entrada por cada
'variable' independiente que dispongan los individuos
representados por la funcion objetivo a maximizar.


2.1- Seleccin de la funcin a maximizar

Al elegir el parametro 'Generacion' y 'Seleccion' se activa
un campo donde es posible ingresar la funcin que se desea
maximizar (para minimizar funciones, referirse a la seccin
sobre escaladores de fitness).
Para permitir la maximizacion de funciones definidas por el
usuario se implement un individuo capaz de parsear una
funcin de varias variables en tiempo de ejecucion
(ref: com.brownsoft.ag.individuo.FuncionExpresion y
com.brownsoft.ag.individuo.IndividuoMultipleFuncionExpresion)
Esto brinda la ventaja de poder probar funciones definidas
por el usuario en cualquier momento sin necesidad de
recompilar ningun archivo fuente, aunque con la desventaja
que supone el parsear la funcion para cada individuo a fin
de obtener su fitness.
Una vez ingresada (o modificada) la funcion objetivo en el
campo provisto para ello, al presionar <Enter> se calcula
automticamente la cantidad de variables con que consta
dicha funcin y se agregan los items necesarios al
combo de seleccion de opciones para poder customizar los
parametros de dichas variables.
El motor no necesita recalcular el fitness de los
individuos repetidos (los mantiene en un cache de
fitnesses) por lo tanto a medida que el algoritmo avanza,
la performance del mismo ir aumentando.
Se pueden definir funciones de 1 o varias variables (cada
variable define un cromosoma del individuo).
El formato de las expresiones permite utilizar constantes
numericas, PI, los operadores +, -, *, / y las siguientes
funciones matematicas (donde A y B son a su vez expresiones)
  - pow(A,B) retorna la potencia A^B
  - sqrt(A) retorna la raz cuadrada de la expresion A
  - cos(A), sin(A), tan(A) retorna el coseno, seno y
     tangente de A
  - acos(A), asin(A), atan(A) retorna el arcocoseno,
      arcoseno y arcotangente de A
  - floor(A) retorna mayor entero menor a A
  - round(A) redondea la expresion A al entero ms prximo
  - exp(A) retorna e^A
  - ln(A) retorna el logartmo neperiano de A
  - abs(A) retorna el valor absoluto de A
  - int(A) retorna la parte entera de la expresion A
  - frac(A) retorna la parte fraccionara de A
  - max(A,B) retorna el mximo entre A y B
  - min(A,B) retorna el mnimo entre A y B
  - rnd() retorna un nmero aleatrio entre 0 y 1


2.1.1- Funcin de 1 variable

Cuando la funcin es de una nica variable, el valor
asociado a una instancia en particular se obtiene mediante
la expresion 'x'. (Internamente, el individuo pasa a ser
una instancia de com.brownsoft.ag.FuncionExpresion)
Ejemplos de funciones de 1 sola variable:
 ->  pow(x,2)
 ->  max(exp(x/2), pow(1+frac(x), 3))
 ->  (PI * pow(x,2))/2


2.1.2- Funcin de varias variables

Cuando la funcin es de varias variables, el valor asociado
a cada variable de una instancia en particular se obtiene
mediante las expresiones 'f(I)' donde I es un entero entre
1 y la cantidad de variables. (Internamente, el individuo
pasa a ser una instancia de com.brownsoft.ag.IndividuoMultip
leFuncionExpresion)
Ejemplos de funciones de varias variables:
  -> pow(f(1), f(2))
  -> (f(1)+f(2)+f(3))/(f(4))
  -> f(1) * 10 * cos(f(2))


2.1.3- Funciones de variables enteras y variables continuas

Las funciones pueden tomar valores enteros o continuos.
Para ello se define el bitWidth de cada variable (la
cantidad de bits con que expresar material genetico).
Si se especifica una cantidad de bits igual a 0, se utilizan
individuos que toma valores enteros y la cantidad de bits
se acomoda automticamente para poder expresar todo el rango
Si se especifica una cantidad de bits mayor a 0, se utiliza
esa cantidad de bits para expresar el rango con valores
en punto fijo (todos los puntos del espacio equidistantes)


2.2- Generacin

Este submenu permite customizar la instancia de Generacion
que el motor va a utilizar.
Las opciones vlidas son:
  - Simple:
     No se define una condicin especial de parada, sino que
     al llegar a las 10 iteraciones se indica que la
     condicin se ha alcanzado.
  - DeJong:
     Se utiliza la medida de performance on-line definida
     por DeJong para obtener la condicin de parada del
     algortmo.
Para todas las opciones adems se debe especificar la
probabilidad de mutacin, la probabilidad de cruzamiento y
la poblacion inicial.


2.3- Seleccin

Este submenu permite elegir el operador de Seleccion a
utilizar.
Las opciones vlidas son:
  - Ruleta:
     Realiza la seleccion mediante el mtodo de la ruleta.
     Con este operador, al iniciar cada iteracion se ordenan
     todos los individuos de la poblacion y se les asigna
     una porcion de una ruleta de acuerdo al fitness que
     tengan. Luego, se tira la ruleta y se elige un punto de
     la ruleta al azar y se elige el individuo asignado a
     esa porcin de la ruleta.
  - Estocastica Universal
     Realiza una seleccion estocstica universal (Stochastic
     Universal Selection).
     En este tipo de seleccion, al iniciar la iteracin se
     gira una vez la ruleta pero con M punteros (donde M
     es la cantidad de individuos a elegir para esta
     iteracin). De esta manera a los individuos que cuya
     porcion de ruleta que sea mayor que la distancia entre
     los punteros se les va a seleccionar al menos una vez.
     Este mtodo tiene las ventajas de no tener sesgo y de
     que su dispersin es mnima.
  - Torneo QK:
     En cada seleccion se eligen K individuos al azar. De
     estos K individuos se eligen los Q con mejor fitness
  - SeleccionElitista:
     Este operador recibe como parametros otro operador
     genetico de seleccin y aplica una seleccin elitista.
		 Es decir que se utilizara el operador pasado por
		 parametro para seleccionar y al finalizar cada
		 iteracion este operador verifica si el mejor individuo
		 encontrado hasta el momento es parte de la nueva
		 poblacion. En caso de que no lo sea lo inserta en la
		 nueva poblacin.


2.4- Escaladores de fitness

El motor de algoritmos genticos permite asociar una cadena
de escaladores de fitness. Los fitnessScalers le aplican
distintas funciones al fitness de un individuo para obtener
el fitness escalado. Estos scalers son utilizados por
ejemplo para transformar un problema de maximizacin en uno
de minimizacin o viceversa. Otro de los usos de los
escaladores es el de asegurarse que el fitness de un
individuo sea positivo. Por ejemplo si la funcion a
maximizar es 'x' y dentro del espacio de bsqueda(rango)
caen valores negativos, el fitness ser negativo. Algunos
operadores de seleccin no permiten que el fitness sea
negativo (por ejemplo todos los operadores derivados de la
seleccion de tipo Ruleta) por lo cual ser necesario
aplicarles un scaler para mantener positivos dichos fitness.
La biblioteca permite definir cadenas de scalers de
cualquier tamao. En esta aplicacin solo se presentan
algunas de las combinaciones que pueden resultar de
utilidad.
Las mismas son las siguientes:
  - Ninguno:
		 No se asocia ningun scaler al motor, es decir que los
	   fitness se utilizaran tal cual se decodifica la
		 estructura del individuo y se evala la funcion
		 objetivo (por tanto realiza una maximizacin sobre la
		 funcin objetivo)
	- ScalerAxB:
	   Este scaler le aplica un escalado lineal al fitness
		 de la funcin objetivo. Los parmetros de este scaler
		 son A y B, y la funcin escala el fitness mediante
		 la siguiente frmula:
				fitness_escalado = A * fitness + B
	- Inversa:
		 Este scaler convierte el problema de maximizacin de
		 funciones en uno de minimizacin, pues le aplica al
		 fitness la siguiente frmula:
				fitness_escalado = 1 / fitness
		 Para que efectivamente el problema pase a ser de
		 minimizacion se debe asegurar que los valores
		 originales de fitness sean siempre positivos.
		 Si los valores de fitness originales tambin pueden
		 ser negativos lo que se puede utilizar para
		 transformar el problema a uno de minimizacin es
     utilizar la cadena de scalers 'Positivo+AxB' con
		 A=-1 y B=0
	- Positivo:
  	 Este scaler se asegura que el fitness sea siempre
		 positivo. Para mayor referencia sobre como lo logra
     leer el documento de la biblioteca o el cdigo fuente
	- Especiacion:
		 Este scaler implemente un algoritmo de especiacion.
		 Solo funciona con funciones de una sola variable pues
		 trabaja a nivel de los bitstreams del individuo para
		 obtener clusters de similitud y ponderar el fitness
     de un individuo segun el el tamao del cluster.
		 Este scaler es computacionalmente 'pesado' porque debe
		 calcular las distancias entre todos los individuos.
     Recibe como parametro 'sigma', el umbral de distancia
		 de especiacion.
	- Positivo+AxB:
		 Esta opcin define una cadena de scalers por la cual
     primero se realizara un escalado lineal sobre el
		 fitness y luego se asegurara que el fitness resultante
		 sea siempre positivo.
		 Los parametros del scaler son A y B (las constantes
		 del escalado lineal)
	- Positivo+Inversa:
		 Esta opcin define una cadena de scalers por la cual
     primero se realizara una inversion del fitness (para
		 transformar el problema de maximizacin en uno de
		 minimizacion y luego se asegurara que el fitness
	   resultante sea siempre positivo.
	- Inversa+Positivo:
		 Esta opcin es similar a la anterior solo que primero
		 asegura que el fitness sea positivo y luego se le
     aplica la inversa a ese fitness. Este scaler puede
     utilizarse para convertir un problema de maximizacion
	   en uno de minimizacin incluso cuando los fitness
     sin escalar puedan ser negativos


2.5- Variables

Como se explic en la seccin 2.1, esta aplicacion puede
maximizar funciones de 1 o varias variables(cromosomas).
Cada variable tiene asociado los operadores genticos de
cruzamiento y mutacin as como tambin el rango de valores
en los que la variable se puede mover y la cantidad de bits
con que se pueda representar dicho rango.
La razn por la que cada cromosoma tenga su propio operador
gentico de cruzamiento y mutacin est dada por la
implementacin de los individuos (FuncionExpresion
y IndividuoMultipleFuncionExpresion).
Las funciones de varias variables utilizan un esquema por el
cual internamente estan compuestas por varias instancias de
FuncionExpresion, por lo cual cada una de ellas
puede tener distintos operadores genticos.
Por supuesto que el operador gentico de seleccin es uno
solo y corresponde al individuo como un entero y no a cada
una de sus partes (Por ms informacin, referirse a la 
implementacin de estos individuos)
Luego de elegir una variable, aparece un nuevo cuadro donde
se pueden seleccionar los operadores a utilizar, como se
describe en las siguientes subsecciones:


2.5.1- Cruzamiento

Este submenu permite elegir el operador de cruzamiento a
utilizar para este cromosoma.
Las opciones vlidas son:
  - SPX:
     Cruzamiento simple. Este operador realiza un
     cruzamiento tomado 2 individuos y eligiendo un solo
     punto de corte donde se intercambia el material
     genetico para crear dos nuevos individuos con la mezcla
     Internamente este operador esta definido como una
     subclase de MPX con parametro 1
  - MPX:
     Cruzamiento mltiple. Para este operador se debe elegir
     N (la cantidad de puntos de corte de cada individuo).
     Al realizar el cruzamiento se toman 2 individuos y se
     seleccionan N puntos de corte al azar. Luego se crean
     dos nuevos individuos, cada uno tomando partes
     alternativas de informacin gentica de cada padre
     Por ejemplo, si N = 2, y los individuos a cruzar los
     caracterizamos por ABC y DEF, los nuevos individuos
     sern AEC y DBF


2.5.2- Mutacin

Este submenu permite elegir el operador de mutacin a
utilizar para este cromosoma.
La mutacin se va a realizar con la probabilidad definida
en el men Generacin descripto anteriormente.
Las opciones vlidas son:
  - BitFlip:
     Luego de realizado el cruzamiento, se recorre bit a bit
     el genotipo de los mismos y con probabilidad pMut se
     invierte el valor de dicho bit.
  - HillClimber:
     Este tipo de mutacin toma como parmetro adems de la
     probabilidad de mutacin (pMut), la cantidad de bits a
     testear(N).
     Luego de realizado el cruzamiento y para cada individuo
     se determina con probabilidad pMut si se va a intentar
     mutar a este individuo o no.
     Si se va a intentar mutar al individuo, se itera N
     veces eligiendo cada vez al azar una posicion(bit) del
     genotipo del individuo y se intercambia su valor. Si
     el nuevo individuo tiene mejor fitness se repite el
     proceso hasta haber probado con N bits. Si por el
     contrario el nuevo individuo tiene peor fitness, se
     descarta dicho bit-flip y se se sigue iterando (hasta
     haber llegado a las N iteraciones).
     De esta manera este algoritmo de mutacin combina
     los algoritmos genticos con una suerte de bsqueda por
     fuerza bruta en un entorno de vecindad de cada
     individuo.


2.5.3- Rango

Este submenu permite elegir el rango de valores en que la
variable podr tomar valores, y la precision de la misma
Los individuos implementados para esta aplicacin utilizan
punto fijo para expresar el rango de valores
Los parametros que se deben definir son:
  - Desde:
     Indica el limite izquierdo del dominio de la variable.
  - Hasta:
     Indica el limite derecho del dominio de la variable.
  - Bits:
     Indica la cantidad de bits(precision) que se va a
     utilizar para representar el material gentico de este
     cromosoma. Dadas las caractersticas del lenguaje Java
     y de la implementacin que se realizo para tener buena
     eficiencia, la cantidad de bits no puede superar los
     63 bits.


3- Botones de comando

A la derecha del panel de controles se encuentran los
botones de comando del motor:
 - Ayuda:
    Activa o desactiva el panel superior de la aplicacin
    que despliega la ayuda de la misma (este texto)
 - Correr:
    Si el motor NO estaba inicializado, inicia el motor con
    los parametros definidos actualmente por el usuario y
    ejecuta una corrida del mismo hasta que la condicin de
    parada del algortmo sea cumplida.
    Si el motor ya estaba inicializado entonces realiza 50
    iteraciones.
    Una vez que el motor est inicializado ya no ser
    posible modificar parmetros del mismo hasta no haber
    reseteado el motor
 - Paso:
    Si el motor NO estaba inicializado, inicia el motor con
    los parametros definidos actualmente por el usuario.
    Ejecuta una iteracin.
    Una vez que el motor est inicializado ya no ser
    posible modificar parmetros del mismo hasta no haber
    reseteado el motor
 - Reset:
    Resetea el estado del motor, permitiendo volver a
    modificar los parametros y/o seleccionar una nueva
    funcion en la aplicacin.


4- Despliegue grfico de la poblacin actual

Cuando el motor est inicializado, en la zona central de la
ventana de la aplicacin se desplegar grficamente el
estado actual de la poblacin.
Dependiendo de si la funcin objetivo es de 1 o ms
variables la informacin graficada ser diferente
En todo momento se desplegar informacin sobre el mejor
individuo encontrado hasta el momento, y el nmero de
iteracin.
Para el caso en que se haya elegido una generacin del tipo
DeJong, se desplegar tambin la performance on-line y
off-line actual.
De ser posible, tambin se dibujarn los ejes de la funcin,
tenindo que no van a estar necesariamente centrados en la
pantalla.
Cuando el rango de valores que toman los individuos
comprende en su interior el valor 0 (ya sea x=0 o y=0), se
dibujar en pantalla el eje representando dicho valor.
En caso contrario (el valor 0 no se encuentra en el rango
de los individuos) entonces el eje representar el punto
medio (matemtico) en los valores de la poblacin actual.
Por ejemplo, si en la poblacin actual el valor funcional
de los individuos comprende el rango (100, 240) entonces
el eje de las ordenadas representar el valor y=170
Cuando toda la poblacin se encuentre contenida en un valor
fijo (ya sea de ordenadas o de abcisas), se mostrara en
pantalla un mensaje indicndolo(Poblacion contenida en X=..)


4.1- Despliegue grfico para individuos de 1 sola variable

En este caso en la pantalla se deplegar para cada individuo
en el eje de las abcisas(x) el valor que toma la variable y
en las ordenadas(y) el valor funcional que toma dicho
individuo.
Es decir que se desplegar la informacin x versus y


4.2- Despliegue grfico para individuos de varias variables

En este caso en la pantalla se deplegar para cada individuo
en el eje de las abcisas(x) el valor que toma alguna de las
variables (cromosomas) y en las ordenadas(y) el valor
funcional que toma dicho individuo.
Es decir, que en cada momento solo se ver un corte parcial
de la funcion, f(I) versus y
La seleccin sobre cual variable tomar en cuenta para el
despliegue se selecciona desde el panel de control.


4.3- Manejo de Zooming, panning, etc sobre el grfico

como se explico anteriormente, en la pantalla se desplegara
si es posible los ejes vertical y horizantal. Para poder
visualizar mejor una posicion (x, y) basta con mover el
puntero del mouse sobre la grafica y en la barra de estado
se informa de las coordenadas de la grfica.
Si se desea diferenciar los distintos puntos de la grfica
se puede clickear sobre la misma y la forma y tamao de
stos ira cambiando.
Por defecto el rea de visualizacin de la grafica se va
moviendo con el algoritmo. Es decir que en cada iteracin
se calcula el rea a ser desplegada. Si se desea mantener
fija el rea de la grfica se debe dejar marcado el
checkbox 'Fijar Grilla'.
Otra de las funcionalidades del control grfico
implementado en esta biblioteca es la de realizar zooming
sobre la grfica.
Para ello basta con presionar el botn izquierdo sobre uno
punto de la grfica y mientras se mantiene presionado el
boton se puede seleccionar un rea donde realizar el zoom.
Para realizar un zoom out simplemente se debe clickear el
botn derecho del mouse y la grafica se 'alejara'
