\chapter{Modi di utilizzo del tool}\label{chapModiUtilizzo}
Ci sono quattro modalità di utilizzo sel software: validazione, ottimizzazione globale, ottimizzazione bilanciata, ottimizzazione incrementale.

\section{Validazione}
In questa modalità vengono considerati esclusivamente gli Hard Constraint senza tenere conto della Funzione obiettivo \eqref{funObiettivo}. Operando in questo modo viene istanziata una sottoparte del modello escludendo \(X\_penalties_p\), \(X\_penaltiesStud_{pStud}\) e \(X\_penaltiesDoc_{pDoc}\) al fine di ottimizzare le performance. L'obiettivo di questa modalità è di ottenere in un tempo minore una risposta positiva/negativa circa la presenza di almeno una soluzione per i dati correnti\footnote{Di norma andrebbe prima lanciata una simulazione in questa modalità e soltanto successivamente in una delle modalità con ottimizzazione.}.

In fase di lancio del tool vengono configurati tutte le sorgenti di dato: 
\begin{itemize}
    \item \textit{add_folderInsegnamentiXml()} per indicare la cartella contenente i file XML con i Template Orario come quello dell'Esempio \ref{bookLocaliXmlSchema}
    \item \textit{set_jsonFileDocenti()} per configurare il file JSON con le preferenze dei Docenti come negli Esempi \ref{esPreferenzeDocentiGen}, \ref{esLimitiGiornalieriDocenti}, \ref{esInsSovrapponibili}, \ref{esAnnoPrecedente} e \ref{esVincoliVariDocente}
    \item \textit{set_jsonFileInsegnamenti()} per configurare il file JSON con le preferenze degli Insegnamenti come nell'Esempio \ref{esPreferenzeDocenti}
    \item \textit{set_fileXmlLocaliAllocati()} per caricare il file XML con i dati dei Locali disponibili come nell'Esempio \ref{esAuleXML}.
    \item \textit{set_nomeSolutions()} per configurare il nome con cui viene salvata la soluzione nel db\footnote{Il nome indicato sarà il prefisso della soluzione seguito da \say{_} e un numero corrispondente al valore della funzione obiettivo per tale soluzione o -1 in caso di lancio in modalità validazione.}
    
    \item \textit{set_capienzaAuleExtended()} per indicare di quanti livelli di capienza dell'Aula superiore a quella necessaria sia possibile allocare un'aula.
\end{itemize}

Di seguito la funzione di lancio della simulazione in modalità validazione:
\begin{lstlisting}
def checkValiditySolution():
    '''Non viene attivato nessun soft constraint, l'obiettivo è solamente verificare la validità della sol proposta. E' utile in caso
    si voglia mantenere buona parte del modello da una precedente allocazione e predisporre una particolare configurazione per certi 
    Insegnamenti o se si vuole testare la compatibilità di hard constraint diversi'''
    p1 = Parameter()
    p1.add_folderInsegnamentiXml(basePath + "/data/nuovi_XML")
    p1.set_jsonFileDocenti(basePath + "/data/nuovo_docenti.json")
    p1.set_jsonFileInsegnamenti(basePath + "/data/nuovo_insegnamenti.json")
    p1.set_fileXmlLocaliAllocati(basePath + "/data/nuove_aule.xml")
    p1.set_nomeSolutions("sim_validation")
    logs.startCall()    
    
    p1.set_capienzaAuleExtended(0)
\end{lstlisting}

\section{Ottimizzazione globale}
In questa modalità viene attivata l'Equazione \eqref{funObiettivo} considerando tutti i Soft Constraint e tutti gli Hard Constraint; la funzione obiettivo risulta essere componibile in modo da poter anche considerare un sottoinsieme delle penalità. Converge alla soluzione matematicamente ottima ma richiede tempi di esecuzione elevati rispetto alla modalità validazione\footnote{Andrebbe usata solo successivamente ad una simulazione in modalità validazione con esito positivo.}.

Viene aggiunto un comando per indicare i componenti della funzione obiettivo da ottimizzare tramite chiamate multiple alla funzione \\\textit{add\_optimizeComponent()}, i valori del parametro rappresentano:
% ho messo il  \\ perchè per qualche motivo latex non andava a capo
\begin{itemize}
    \item Parameter.OptimizeComponent.Orientamento: minimizzazione delle penalità relative agli Orientamenti come la sovrapposizione degli Insegnamenti quali quelli di tipo Credito libero, Insegnamento a scelta
    \item Parameter.OptimizeComponent.Studenti: minimizzazione delle penalità relative alla bontà dell'orario in termini di spazi vuoti e slot consecutivi per gli Insegnamenti di un dato Orientamento
    \item Parameter.OptimizeComponent.Docenti: minimizzazione delle penalità rispetto a tutte le preferenze espresse dai Docenti.
\end{itemize}

Di seguito la funzione di lancio della simulazione in modalità ottimizzazione globale:
\begin{lstlisting}
def computeOptimalSolution():
    '''Simile a computeOptimalSolution(). Solo non impongo vincoli ausiliari sulle varie parti di soft constraint (ie non mi interessa
    se la penalità per un Docente sarà superiora alla media, e così via), mi basta puntare a minimizzare la funzione obiettivo.\n
    Potrebbe portare risultati praticamente analoghi a computeOptimalSolution() con meno effort'''  
    p1 = Parameter()
    p1.add_folderInsegnamentiXml(basePath + "/data/nuovi_XML")
    p1.set_jsonFileDocenti(basePath + "/data/nuovo_docenti.json")
    p1.set_jsonFileInsegnamenti(basePath + "/data/nuovo_insegnamenti.json")
    p1.set_fileXmlLocaliAllocati(basePath + "/data/nuove_aule.xml")
    p1.set_nomeSolutions("sim_globalOptimization")
    logs.startCall()    
    
    p1.set_capienzaAuleExtended(0)
    
    p1.add_optimizeComponent(Parameter.OptimizeComponent.Orientamento)
    p1.add_optimizeComponent(Parameter.OptimizeComponent.Studenti)
    p1.add_optimizeComponent(Parameter.OptimizeComponent.Docenti)    
\end{lstlisting}

\section{Ottimizzazione bilanciata}
Coincide con quanto detto per l'ottimizzazione globale, andando inoltre a bilanciare le penalità associate ai vari Docenti al fine di non ottenere soluzioni ottime dal punto di vista di certi Docenti ma pessime per altri: non è affatto scontato che la soluzione matematicamente ottima sia anche quella migliore adottabile.

Il comando \textit{p1.add\_additionalModelConfig()} con parametro \\Parameter.OptimizeComponent.Docenti serve per bilanciare le penalità relative ai Docenti, in maniera analoga è possibile bilanciare le penalità relative agli Orientamenti e agli studenti utilizzando rispettivamente i parametri Parameter.OptimizeComponent.Orientamento e\\ Parameter.OptimizeComponent.Studenti\footnote{Non è necessario utilizzarli in mutua esclusione.}.

Di seguito la funzione di lancio della simulazione in modalità ottimizzazione bilanciata:
\begin{lstlisting}
def computeOptimalSolutionBalanced():
    '''Abilita tutti i meccanismi di penalità al fine di trovare la soluzione ottima'''
    p1 = Parameter()
    p1.add_folderInsegnamentiXml(basePath + "/data/nuovi_XML")
    p1.set_jsonFileDocenti(basePath + "/data/nuovo_docenti.json")
    p1.set_jsonFileInsegnamenti(basePath + "/data/nuovo_insegnamenti.json")
    p1.set_fileXmlLocaliAllocati(basePath + "/data/nuove_aule.xml")
    p1.set_nomeSolutions("sim_balancedOptimization")
    logs.startCall()
    
    p1.add_optimizeComponent(Parameter.OptimizeComponent.Orientamento)
    p1.add_optimizeComponent(Parameter.OptimizeComponent.Studenti)
    p1.add_optimizeComponent(Parameter.OptimizeComponent.Docenti)
    
    # bilanciamento dei Docenti
    p1.add_additionalModelConfig(Parameter.OptimizeComponent.Docenti)
\end{lstlisting}

\section{Ottimizzazione incrementale}
Questa modalità funziona esattamente come l'Ottimizzazione globale utilizzando come base una precedente soluzione ottenuta con una delle modalità precedenti. Vengono quindi definiti esplicitamente gli Insegnamenti\footnote{Tramite l'ID\_INC.} per cui verranno ignorati i dati nella soluzione precedente e che andranno nuovamente allocati.

\begin{itemize}
    \item Il comando \textit{set\_usePianoAllocazioneAsBase(True)} abilita la modalità
    \item Il comando \textit{p1.set\_pianoAllocazioneBase()} configura la soluzione a db da usare come sorgente
    \item Il comando \textit{add\_listID_INCToModify()} indica gli unici Insegnamenti per cui procedere alla riallocazione dell'orario.
\end{itemize}

Di seguito la funzione di lancio della simulazione in modalità ottimizzazione incrementale:
\begin{lstlisting}
def keepOldModelWithMinorChanges_optimize():
    '''Uso un piano allocazione precedentemente creato per buona parte degli Insegnamenti, solo alcuni di essi devono essere modificati,
    voglio trovare la soluzione ottima.'''
    p1 = Parameter()
    p1.add_folderInsegnamentiXml(basePath + "/data/nuovi_XML")
    p1.set_jsonFileDocenti(basePath + "/data/nuovo_docenti.json")
    p1.set_jsonFileInsegnamenti(basePath + "/data/nuovo_insegnamenti.json")
    p1.set_fileXmlLocaliAllocati(basePath + "/data/nuove_aule.xml")
    p1.set_nomeSolutions("sim_incrementalOptimization")
    logs.startCall()    

    p1.set_capienzaAuleExtended(0)

    p1.add_optimizeComponent(Parameter.OptimizeComponent.Orientamento)
    p1.add_optimizeComponent(Parameter.OptimizeComponent.Studenti)
    p1.add_optimizeComponent(Parameter.OptimizeComponent.Docenti)
    
    p1.set_usePianoAllocazioneAsBase(True)
    p1.set_pianoAllocazioneBase("sim_globalOptimization")
    p1.add_listID_INCToModify([259328,261125])
\end{lstlisting}