\documentclass[a4paper,11pt,openany]{article}
\usepackage[top=2.0cm, bottom=2.0cm, left=2.0cm, right=2.0cm]{geometry}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[frenchb]{babel} % If you write in French
\usepackage{graphicx}
\usepackage{subfig}
\usepackage{tikz}
\usepackage{float}
\usepackage{fourier}

\usepackage{minted}
\usemintedstyle[c++]{emacs}

\title{Projet informatique, programmation orientée objet.\\	\vspace{50pt} \textbf{Méthode d'optimisation :\\ \textit{Simulated Annealing} ou le "recuit simulé".}\\ \vspace{50pt} \huge{\textbf{Mode d'emploi.}} \vspace{50pt}}

\author{Thibault Barnouin}

\hyphenpenalty=10000 
\tolerance=2000
\emergencystretch=10pt


\begin{document}
\maketitle
\vspace{100pt}
\tableofcontents
\newpage

\section{Principe d'utilisation.}
	Dans ce mode d'emploi, j'explique l'utilisation du code d'optimisation dont la structure est décrite dans la \textit{Rapport de Projet}.\\
	\indent De façon générale, pour optimiser un modèle sur un set de données il faudra le faire de la façon suivante :
	\begin{enumerate}
		\item Importer les données dans un objet de type \textsf{Data},
		\item Créer un objet de type d'un modèle choisi (noté ici \textsf{ModeleChoisi}) basé sur les données précédemment importées,
		\item Créer un pointeur de type \textsf{Model} vers le modèle ainsi créé,
		\item Créer un objet de type d'une méthode d'optimisation choisie (pour ce projet seul \textsf{SimulatedAnnealing} a été implémenté) basé sur le pointeur précédemment créé,
		\item Initialiser, exécuter et finaliser la méthode d'optimisation.
	\end{enumerate}
	
\vspace{12pt}
\section{Les méthodes spécifiques.}
	\subsection{Méthodes associées aux objets de type \textsf{Data}.}
		Cet objet dispose de plusieurs constructeurs. Supposons que nous voulons créer un objet \textsf{X} de type \textsf{Data} :
		\begin{itemize}
			\item[-] \textsf{Data X} crée l'ensemble vide nommé \textit{Data\_0};
			\item[-] \textsf{Data X(Y)} récupère l'ensemble et le nom de l'objet donné \textsf{Y};
			\item[-] \textsf{Data X("donnéesX")} crée l'ensemble vide nommé \textit{donnéesX};
			\item[-] \textsf{Data X(vector<vector<double>> Tab, "donnéesX")} crée l'ensemble Tab nommé \textit{donnéesX}.
		\end{itemize}\vspace{4pt}
		
		Il dispose aussi de méthodes de génération de données aléatoires :
		\begin{itemize}
			\item[-] \textsf{randSet(int N)} crée un ensemble de \textsf{N} points uniformément tirés dans le carré \textsf{[[0;1],[0;1]]};
			\item[-] \textsf{randSet(int N, double xa, double xb, double ya, double yb)} crée un ensemble de \textsf{N} points uniformément tirés dans le carré \textsf{[[xa;ya],[xb;yb]]};
			\item[-] \textsf{randSet(int N, int d, double mu)} crée un ensemble de \textsf{N} points associés à un modèle polynomial aléatoire de degré \textsf{d} avec un bruit moyen \textsf{mu}.
		\end{itemize}\vspace{6pt}
		
		\textsf{X.fromFile("path")} importe les données du fichier situé à \textsf{path} (ce fichier doit comporter les données sous forme de 2 colonnes de nombres flottants séparées d'un espace).\vspace{6pt}
		
		On peut récupérer et modifier ses attributs via les accesseurs et mutateurs : 
		\begin{itemize}
			\item[-] \textsf{getData()} retourne un ensemble de données, de type \textsf{vector<vector<double>>};
			\item[-] \textsf{setData(vector<vector<double>>)} modifie l'ensemble de données;
			\item[-] \textsf{getName()} retourne le nom de l'ensemble, de type \textsf{string};
			\item[-] \textsf{setName(string)} modifie le nom de l'ensemble.
		\end{itemize}\vspace{4pt}
				
		Pour l'export des données :
		\begin{itemize}
			\item[-] \textsf{displayData()} affiche les données via une fenêtre gnuplot;
			\item[-] \textsf{exportData()} crée un fichier d'extension \textit{.data} portant le nom de l'ensemble et contenant les points de l'ensemble (sous formes de 2 colonnes de nombres flottants séparées d'un espace).
		\end{itemize}
	
	\vspace{8pt}
	\subsection{Méthodes associées aux objets de type \textsf{Model}.}
		Cet objet dispose de plusieurs constructeurs. Supposons que nous voulons créer un objet \textsf{A} de type \textsf{ModeleChoisi} \textit{(on verra en fin de cette section les différents modèles implémentés et leurs spécificités)} :
		\begin{itemize}
			\item[-] \textsf{ModeleChoisi A} crée un modèle vide (les ensembles de données expérimentales et obtenues par les modèle sont vides) avec la fonction de coût associée au modèle;
			\item[-] \textsf{ModeleChoisi A(B)} récupère les attributs de l'objet donné \textsf{B};
			\item[-] \textsf{ModeleChoisi A(Data X)} crée un modèle basé sur les données expérimentales \textit{X}.
		\end{itemize}\vspace{4pt}
		
		On peut modifier les attributs via les mutateurs :
		\begin{itemize}
			\item[-] \textsf{setModelData(Data)} modifie l'ensemble de données du modèle;
			\item[-] \textsf{setExpData(Data)} modifie l'ensemble de données expérimentales;
			\item[-] \textsf{setCost(CostFunction$\ast$)} modifie la fonction du coût associée au modèle;
			\item[-] \textsf{setParam(vector<double>)} modifie les paramètres du modèle.
		\end{itemize}\vspace{4pt}
		
		Pour récupérer les valeurs des attributs via les accesseurs : 
		\begin{itemize}
			\item[-] \textsf{getSol()} retourne l'ensemble de données du modèle, de type \textsf{Data};
			\item[-] \textsf{getParam()} retourne les paramètres du modèle, de type \textsf{vector<double>};
			\item[-] \textsf{getCost()} retourne le coût associé au modèle (comparaison des données expérimentales et modélisées), de type \textsf{double};
			\item[-] \textsf{getNeighbor()} retourne les paramètres d'un modèle \textit{voisin} du modèle courant, de type \textsf{vector<double>}.
		\end{itemize}\vspace{4pt}
		
		Pour l'export des données :
		\begin{itemize}
			\item[-] \textsf{displayModel()} affiche les données expérimentales et modélisées via une fenêtre gnuplot,
			\item[-] \textsf{exportModel()} crée un fichier d'extension \textit{.data} portant le nom du modèle et contenant les points expérimentaux et modélisés (sous formes de 4 colonnes de nombres flottants séparées d'un espace).
		\end{itemize}\vspace{8pt}
		
		Les différents modèles implémentés et leurs spécificités : 
		\begin{itemize}
			\item[•] \textsf{LinearApprox} est un modèle linéaire, la fonction de coût associée est $\chi{2}$ l'écart quadratique, les paramètres associés sont l'ordonnée à l'origine et la pente, un modèle \textit{voisin} est un modèle pour lequel les paramètres courants ont été légèrement perturbés;
			\item[•] \textsf{PolynomialApprox} est un modèle polynomial, la fonction de coût associée est $\chi{2}$ l'écart quadratique, les paramètres associés sont les coefficients du polynôme modélisateur, un modèle \textit{voisin} est un modèle pour lequel les paramètres courants ont été légèrement perturbés;
			\item[•] \textsf{TSP} est un modèle du voyageur de commerce \textit{(Traveling SalesPerson)}, la fonction de coût associé est la distance totale, les paramètres associés sont l'ordre de visite des villes, il existe plusieurs définitions du modèle \textit{voisin} : la définition retenue modifie l'ordre des villes d'un sous ensemble du chemin parcouru par le modèle courant.
		\end{itemize}
		
	\vspace{8pt}
	\subsection{Méthodes associées aux objets de type \textsf{OptimisationMethod}.}
		Cet objet dispose de plusieurs constructeurs. Supposons que nous voulons créer une méthode d'optimisation \textsf{M} de type \textsf{MethodeChoisie} \textit{(la seule méthode implémentée pour ce projet est celle dite du "recuit simulé" (Simulated Annealing) que l'on précisera par la suite).} :
		\begin{itemize}
			\item[-] \textsf{MethodeChoisie M} est un constructeur spécifique à la méthode qui initialise des paramètres par défaut pour un modèle vide;
			\item[-] \textsf{MethodeChoisie M(Model$\ast$ A)} construit la méthode et initialise des paramètres par défaut pour optimiser le modèle pointé par \textsf{A}.
		\end{itemize}\vspace{4pt}
		
		Pour utiliser la méthode : 
		\begin{itemize}
			\item[-] \textsf{initialise()} initialise les paramètres à partir des valeurs entrées dans le ficher \textit{header} correspondant à la méthode choisie;
			\item[-] \textsf{execute()} exécute la méthode d'optimisation;
			\item[-] \textsf{finalise()} exporte et affiche le modèle optimisé.
		\end{itemize}\vspace{8pt}
		
		La seule méthode implémentée pour ce projet informatique est la méthode dite du "recuit simulé" \textit{(Simulated Annealing)}. On l'appelle par \textsf{SimulatedAnnealing}, ses paramètres sont : l'amplitude des perturbations, la température initiale et la température finale du modèle, le taux de refroidissement, le nombre d'itération à une température constante et le nombre maximal de rejet de solutions avant de considérer le modèle gelé.\\
		\indent \small{\textsf{SimulatedAnnealing M(Model$\ast$ A, double $ampl$, double $T_{ini}$, double $T_{fin}$, double $\tau_{froid}$, int $N_{isoT}$, int $m_{gel}$)}} \normalsize{permet de construire la méthode avec les paramètres de notre choix sans passer par la modification des variables dans \textit{SimulatedAnnealingParameters.h} (\danger dans ce cas ne pas utiliser \textsf{M.initialise()}).}
		
\vspace{12pt}
\section{Exemples d'utilisation.}
	\subsection{Approximation linéaire d'un modèle bruité}
		\begin{minted}{c++}
#include<stdlib.h>
#include<time.h>
#include"models.h"
#include"methods.h"

int main(){
	srand(time(NULL));
	
	//Créer un ensemble de données Exp1 nommé "Expérience1"
	Data Exp1("Experience1");
	//Générer 100 point aléatoirement suivant un modèle affine (polynomial de degré 1)
	Exp1.randSet(100,1,1.);
	//Créer un modèle linéaire basé sur les données expérimentales Exp1	
	LinearApprox Lin1(Exp1);
	
	//Créer un pointeur de type Model vers le modèle linéaire
	Model* Mod1 = new LinearApprox(Lin1);
	
	//Créer la méthode d'optimisation pour le modèle linéaire
	SimulatedAnnealing Opti1(Mod1);
	Opti1.initialise();
	Opti1.execute();
	Opti1.finalise();
	
	free(Mod1);
	
	return 0;
}
		\end{minted}
	
	\subsection{Approximation polynomiale d'un modèle bruité}
		\begin{minted}{c++}
#include<stdlib.h>
#include<time.h>
#include"models.h"
#include"methods.h"

int main(){
	srand(time(NULL));
	
	//Créer un ensemble de données Exp2 nommé "Expérience2"
	Data Exp2("Experience2");
	//Générer 100 point aléatoirement suivant un modèle polynomial de degré 2
	Exp2.randSet(100,2,1.);
	//Créer un modèle polynomial de degré 2 basé sur les données expérimentales Exp2
	PolynomialApprox Pol2(Exp2,2);
	
	//Créer un pointeur de type Model vers le modèle polynomial
	Model* Mod2 = new PolynomialApprox(Pol2);
	
	//Créer la méthode d'optimisation pour le modèle polynomial
	SimulatedAnnealing Opti2(Mod2);
	Opti2.initialise();
	Opti2.execute();
	Opti2.finalise();
	
	free(Mod2);

	return 0;
}
		\end{minted}
		
	\subsection{Application au problème du voyageur de commerce}
		\begin{minted}{c++}
#include<stdlib.h>
#include<time.h>
#include"models.h"
#include"methods.h"

int main(){
	srand(time(NULL));
	
	//Créer un ensemble de données Villes nommé "30Villes"
	Data Villes("30Villes");
	//Générer 30 point distribué uniformément sur le carré [[0;1],[0;1]]
	Villes.randSet(30);
	//Créer un modèle du voyageur de commerce sur la base de la distribution Villes
	TSP TSP30(Villes);
	
	//Créer un pointeur de type Model vers le modèle du voyageur de commerce
	Model* Mod = new TSP(TSP30);
	
	//Créer la méthode d'optimisation pour le modèle du voyageur de commerce
	SimulatedAnnealing Opti(Mod);
	Opti.initialise();
	Opti.execute();
	Opti.finalise();
	
	free(Mod);

	return 0;
}
		\end{minted}

\addcontentsline{toc}{section}{Commentaires supplémentaires}
\section*{Commentaires supplémentaires.}
	Le code ainsi écrit permet facilement d'ajouter des modèles ou méthodes d'optimisation.\\
	\indent Pour la génération aléatoire de données, il pourrait être intéressant d'ajouter un méthode qui prend en argument un pointeur vers une fonction-modèle définie par l'utilisateur. De la même façon, un modèle basé sur une fonction définie par l'utilisateur pourrait aussi être pertinent.\vspace{7pt} \\
	\indent On a pu le voir pour la méthode de "recuit simulé", l'efficacité d'optimisation de la méthode dépend très fortement du modèle étudié. Une optimisation des paramètres de la méthode par rapport au modèle serait alors une bonne façon d'optimiser l'optimisation !
\end{document}