\chapter{Progettazione}\label{chapProgettazione}

\section{Modelli adottati}
Di seguito la rappresentazione rigorosa del modello in UML in grado di rispettare tutti i requisiti esposti nel capitolo precedente. Successivamente vengono definiti i formati scelti per l'input dei dati all'interno del software.

\subsection{Modello UML globale}
Data la vastità del modello l'analisi del modello è suddivisa in più porzioni:
\begin{itemize}
    \item Corso di Laurea, Orientamento e Insegnamento:
    
La porzione di modello in Figura~\ref{fig:UML_insegnamento} evidenzia i molteplici Orientamenti all'interno di un dato Corso di Laurea; inoltre gli studenti si iscrivono ad un dato Orientamento e di conseguenza ai diversi Insegnamenti di afferenza a questo. Inoltre ogni Orientamento è costituito da più Insegnamenti e per ognuno di questi vi sono alcuni dati molto rilevanti tra cui:

\begin{figure}[tb]
    \centering
    \includegraphics[width=\textwidth]{images/figures/CDL Orientamento Insegnamento.png}
    \caption{Modello UML che descrive l'Insegnamento.}
    \label{fig:UML_insegnamento}
\end{figure}

\begin{itemize}
    \item ID\_INC: rappresenta l'identificativo dell'Insegnamento all'interno del modello.
    \item\textit{listCodIns}: un dato Insegnamento viene identificato nei vari piani studi pubblicamente disponibili con codici differenti a seconda dell'Orientamento in cui è presentato\footnote{Poichè lo stesso Insegnamento può essere molto numeroso è possibile esistano differenti Alfabetiche per lo stesso (quindi diversi ID\_INC) e ciò può portare ad avere anche casi in cui lo stesso \textit{codIns} si riferisca a più ID\_INC.}.
    \item\textit{nStudenti} e \textit{nStudentiFreq}: i loro valori sono conseguenza della relazione \textit{Studente\_in\_Insegnamento}.
\end{itemize}
La relazione \textit{Insegnamento\_in\_Orientamento} contiene al suo interno l'attributo \textit{nStudenti} che permetterebbe di dosare meglio le penalità a seconda degli Orientamenti a cui si riferiscono, tuttavia non è stato possible ricavare tali dati e quindi al momento risulta inutilizzata.

I tipi associati agli attributi sono riportati qui di seguito:
\begin{lstlisting}
tipoCdl in ['1', 'Z'] # il Corso di Laurea è rispettivamente Triennale o Magistrale
tipoInsegnamento in [Obbligatorio, ObbligatorioAScelta, CreditoLibero, TabellaAScelta]
statoFreq in [Attivo, NonFrequentante, FrequenzaConvalidata] # a causa dei dati a disposizione si utilizza direttamente il numero di Studenti al primo anno di frequenza nel software
\end{lstlisting}
\FloatBarrier



\item Insegnamento e Docenti:

\begin{figure}[tb]
    \centering
    \includegraphics[width=\textwidth]{images/figures/Insegnamento Docente.png}
    \caption{Modello UML che descrive gli Insegnamenti del Docente.}
    \label{fig:UML_insegnamenti_docente}
\end{figure}

La parte di modello in Figura~\ref{fig:UML_insegnamenti_docente} riporta le relazioni tra Docenti e Insegnamenti:
\begin{itemize}
\item\textit{Insegnamento\_Conflitto} si occupa della modellazione dei vincoli dovuti all'appartenenza di un Insegnamento ad uno o più Orientamenti.
\item\textit{Preferenza\_Docente}: data la disomogeneità di possibili constraint modellabili questa parte verrà approfondita successivamente andando ad esaminare i dati richiesti in input dal software.
\item\textit{Insegnamento\_ha\_titolare} risulta utile in quanto soltanto tale Docente ha il compito di fornire i dati di cui ai punti precedenti.

\end{itemize}

I tipi associati agli attributi precedentemente non introdotti sono riportati qui di seguito:
\begin{lstlisting}
livelloConflitto in [LVH, LV1, LV2, LV3, LV4, LV5] # LVH corrisponde al modellare un hard constraint, mentre gli altri valori corrispondo a degli interi progressivi
giorno in [Lun, Mar, Mer, Gio, Ven, Sab, 'Indifferente']
fasciaOraria in [8.30-10.00, 10.00-11.30, 11.30-13.00, 13.00-14.30, 14.30-16.00, 16.00-17.30, 17.30-19.00, 'Indifferente']
tipoPreferenza in ['incompatibilita', 'maxSlotPerDay', 'insegnamentiSovrapponibili', 'preferenzeAnnoPrecedente', 'orariLezioniDocente', 'distanzaMinima', 'distanzaMassima', 'insegnamentiDiversiSameDay']
livelloPreferenza in [LVH, LV1, LV2, LV3, LV4, LV5]
logicaTemporale in ['primaDi', 'dopoDi', 'ugualeA']
logicaPreferenza in ['favorevole', 'contrario']
\end{lstlisting}



\item Slot Insegnamento e Docenti:

\begin{figure}[tb]
    \centering
    \includegraphics[width=.9\textwidth]{images/figures/Slot Insegnamento Docente.png}
    \caption{Modello UML che descrive gli Slot di un Insegnamento.}
    \label{fig:UML_slot_insegnamento}
\end{figure}

Dal modello in Figura~\ref{fig:UML_slot_insegnamento} si evince che un Insegnamento è costituito da uno o più Slot.\\Per ogni Slot esistono alcune relazioni e alcuni attributi di interesse:
\begin{itemize}
\item\textit{Docente\_in\_Slot}: in un dato Slot è possibile che più Docenti facciano lezione\footnote{Potrebbe trattarsi di compresenze oppure più semplicemente di lezioni tenute in settimane o periodi differenti del semestre da Docenti differenti.}. \`E necessario elencare puntualmente tutti i Docenti che dovranno tenere tale lezione poichè sarà necessario evitare sovrapposizioni con altri Slot in cui è presente anche solo uno dei Docenti elencati\footnote{Salvo richieste esplicite dei Docenti trattate puntualmente.}.
\item\textit{Slot\_ha\_SlotSettimana}: ogni Slot deve essere identificato temporalmente all'interno nella settimana; inoltre l'attributo \textit{numSlotConsecutivi} ha il compito di considerare più slot orari come un'unica entità che deve necessariamente essere allocata in un unico blocco contiguo\footnote{Seppur sia possibile istanziare due Slot di durata inferiore ed un vincolo di contiguità per ottenere il medesimo risultato che si ottiene istanziando un unico Slot ove \textit{numSlotConsecutivi} corrisponde alla somma degli altri due; è preferibile istanziare un unico Slot al fine di dimezzare le variabili introdotte nel modello, come verrà illustrato in seguito.}.
\item\textit{squadra}: attributo opzionale che se presente in due diversi Slot dello stesso Insegnamento e con valore diverso consente al software di allocarli {anche} parallelamente\footnote{Di norma due Slot afferenti allo stesso Insegnamento non possono essere allocati in parallelo poichè ogni studente deve poter seguire tutte le lezioni dello stesso.}.
\item\textit{Vincolo\_in\_Slot}: viene concesso ampio margine gestionale ai titolari degli Insegnamenti consentendo loro di personalizzare con un elevato livello di dettaglio i vari Slot che compongono il singolo Insegnamento; si tratta di relazioni binarie il cui significato è autoesplicativo dai nomi stessi\footnote{Il software è corredato di un linguaggio booleano elementare che consente di esprimere espressioni più o meno complesse mediante gli operatori \textit{OR}, \textit{AND} e \textit{NOT}.}.
\end{itemize}
I tipi associati agli attributi precedentemente non introdotti sono riportati qui di seguito:
\begin{lstlisting}
giorno in [Lun, Mar, Mer, Gio, Ven, Sab, 'Indifferente']
fasciaOraria in [8.30-10.00, 10.00-11.30, 11.30-13.00, 13.00-14.30, 14.30-16.00, 16.00-17.30, 17.30-19.00, 'Indifferente']
tipoLezione in [L, EA, EL, L_EA] # rispettivamente Lezione, Esercitazione Aula, Esercitazione Laboratorio, Lezione o Esercitazione in Aula.
livelloVincolo in [LVH, LV1, LV2, LV3, LV4, LV5]
tipoVincolo in ['almenoUnGiornoDopo', 'subitoDopo', 'stessoGiorno', 'giornoDiverso', 'parallelo']
squadra in ['Squadra 1', 'Squadra 2', 'Squadra 3', 'Squadra 4'] # opzionale, se non specificato si intende che lo Slot non sia riferito ad una specifica squadra
\end{lstlisting}
\FloatBarrier
    
    
    
\item Slot e Locali:

\begin{figure}[tb]
    \centering
    \includegraphics[width=.85\textwidth]{images/figures/Slot Locali.png}
    \caption{Modello UML che descrive i tipi di Locale per gli Slot.}
    \label{fig:UML_locale_slot}
\end{figure}

L'entità Locale ed i suoi figli riportati in Figura~\ref{fig:UML_locale_slot} contengono le informazioni relative agli spazi fisici disponibili e assegnabili:
\begin{itemize}
\item\textit{preseElettriche} e \textit{tipoLocale} permettono di assegnare al singolo Slot un Locale che rispetti i requisiti.
\item\textit{capienza} permette classificare i Locali in differenti gruppi a seconda della capienza\footnote{Seppur valorizzabile, l'informazione sulla capienza di un'Aula trova riscontro pratico solamente per le Aule e i locali ad essa affini in quanto un dato laboratorio non esiste in istanze multiple con capienza differente.}.
\end{itemize}
La relazione \textit{Locale\_Distanza} permette di quantificare la distanza tra Locali al fine di minimizzare gli spostamenti tra Locali differenti al variare degli Slot di lezione erogati.

I tipi associati agli attributi precedentemente non introdotti sono riportati qui di seguito:
\begin{lstlisting}
preseElettriche in ['Si', 'No', 'Preferibile']
tipoLocale in ['Aula', 'Aula multimediale', 'Aula attrezzata CA2', 'Aula attrezzata CA', 'Aula TableBox', 'Aula WallBox', 'LABINF', 'LAIB', 'LADISPE', 'LED', 'LED1', 'LED2', 'ACSLAB', 'Aula 5T']
capienza in ['Piccola', 'Media', 'MedioGrande', 'Grande', 'NonDisponibile']
\end{lstlisting}
\FloatBarrier

\end{itemize}





\subsection{Modello UML Template Orario}

Il software è progettato per ricevere separatemente un'istanza del modello UML che rapresenta un   \textit{Template Orario} per ogni insegnamento che deve essere allocato. 
Un Template Orario rappresenta i requisti espressi Docenti titolari di un Insegnamento in termini di organizzazione settimanale degli slot orari da erogare, informazioni sui Docenti che terranno la lezione in tali slot orari, i Locali richiesti per erogare specifiche lezioni, squadre a cui si riferiscono i diversi Slot.
% \todo[inline]{preseElettriche nel padre}
\begin{itemize}
\item Template Orario e SlotTemplate:
    
\begin{figure}[tb]
    \centering
    \includegraphics[width=.85\textwidth]{images/figures/TemplateOrario e SlotTemplate.png}
    \caption{Modello UML che descrive il TemplateOrario.}
    \label{fig:UML_template_orario}
\end{figure}

Larga parte del modello UML corrisponde a quello globale in quanto questa è una sua estensione, di seguito vengono spiegate nel dettaglio alcune scelte fatte.
In particolare il \textit{TemplateOrario} in Figura~\ref{fig:UML_template_orario} rappresenta la modellazione dell'orario dell'Insegnamento ed è una collezione di \textit{SlotTemplate} che lo definiscono, tra i suoi attributi vi sono:
\begin{itemize}
    \item\textit{id}: costituisce l'identificativo dell'Insegnamento per l'utente (mentre per il software risulta essere \textit{ID\_INC}) e corrisponde al titolo dell'Insegnamento (sono ammessi duplicati in quanto lo scopo è di rendere maggiormente \say{user friendly} l'esperienza d'uso del software.
    \item\textit{capienzaAula}: i Docenti potranno scegliere arbitrariamente la capienza delle Aule da assegnare ai loro Slot, tuttavia questa scelta è preferibilmente da evitare in quanto sarebbe più corretto affidare la gestione della capienza dell'Aula rischiesta in un dato Slot al software stesso in quanto il software è in grado di dedurre la capienza adatta allo Slot in funzione del \textit{numeroIscritti} all'Insegnamento o allo Slot (se specificato).
\end{itemize}
L'entità \textit{SlotTemplate} rappresenta l'unita elementare allocabile nell'orario prevedento tra le altre cose:
\begin{itemize}
    \item\textit{tipo}, \textit{tipoErogazione} e \textit{note}: attributi solamente descrittivi che permettono un'immediata lettura delle soluzioni generate.
    \item\textit{locale} \textit{numIscritti}, e \textit{preseElettriche}: determinano la scelta del Locale da assegnare allo Slot.
    \item\textit{docente}: tenendo traccia dei Docenti associati allo Slot è possibile evitare casi di sovrapposizione che porterebbero uno o più Docenti ad aver contemporaneamente allocate più lezioni.
    \item\textit{Vincolo\_in\_Slots}: rispecchia i criteri già introdotti nel modello UML globale. 
\end{itemize}
I tipi associati agli attributi sono riportati qui di seguito:
\begin{lstlisting}
capienzaAula in ['Piccola', 'Media', 'MedioGrande', 'Grande']
tipoLezione in [L, EA, EL, L_EA]
tipoErogazione in ['Presenza', 'Remoto']
locale in ['Aula', 'Aula multimediale', 'Aula attrezzata CA2', 'Aula attrezzata CA', 'Aula TableBox', 'Aula WallBox', 'LABINF', 'LAIB', 'LADISPE', 'LED', 'LED1', 'LED2', 'ACSLAB', 'Aula 5T']
livelloVincolo in [LVH, LV1, LV2, LV3, LV4, LV5, LV_MAX]
tipoVincolo in ['almenoUnGiornoDopo', 'subitoDopo', 'stessoGiorno', 'giornoDiverso', 'parallelo']
preseElettriche in ['Si', 'No', 'Preferibile']
\end{lstlisting}
% \todo[inline]{remove preseElettriche, desc day, fasciaOraria}
\FloatBarrier



\begin{figure}[tb]
    \centering
    \includegraphics[width=\textwidth]{images/figures/Tipi Slot.png}
    \caption{Modello UML che descrive i tipi di slot.}
    \label{fig:UML_tipi_slot}
\end{figure}

\item I tipi di Slot sono riportati in Figura~\ref{fig:UML_tipi_slot}. 
Viene estesa l'entità Slot osservando che non è possibile un approccio completamente uniforme in quanto alcuni di essi abbiano requisiti molto più stringenti di altri per vari motivi. Si progettano quindi tre entità derivate da \textit{SlotTemplate}:
\begin{itemize}
\item\textit{SlotScelto}: consente di raccogliere i requisiti più stringenti in assoluto per uno Slot permettendo l'allocazione di esso in un giorno e/o ad un'ora precisa.
\item\textit{SlotGenerico}: rappresenta uno Slot che non ha prerequisiti in termini di giorno e fasciaOraria. L'attributo \textit{squadra} comune ad entrambi i tipi di Slot consente di gestire correttamente lezioni da non allocare all'intera platea di studenti ma solo ad una sua sottoparte permettendo in assenza di altri vincoli un'allocazione eventualmente parallela di più Slot\footnote{L'allocazione parallela di Slot non è forzata (esplicabile come vincolo), ma solo consentita in assenza di vincoli quali la presenza di Docenti differenti nei differenti Slot appartenenti a squadre diverse.}.
\item\textit{SlotPreferito}: consente ai Docenti di definire opzioni multiple più o meno appetibili a seconda dell'attributo \textit{penalità}. Ognuna di queste opzioni sarà costituita da uno o più Slot dei due tipi elementari precedentemente introdotti.
\end{itemize}




I tipi associati agli attributi sono presentati di seguito:
\begin{lstlisting}
tipoScelta in ['SlotPreciso', 'NonPrima', 'NonDopo']
squadra in ['Squadra 1', 'Squadra 2', 'Squadra 3', 'Squadra 4']
giorno in [Lun, Mar, Mer, Gio, Ven, Sab, 'Indifferente']
fasciaOraria in [8.30-10.00, 10.00-11.30, 11.30-13.00, 13.00-14.30, 14.30-16.00, 16.00-17.30, 17.30-19.00, 'Indifferente']
livelloVincolo in [LVH, LV1, LV2, LV3, LV4, LV5]
tipoVincolo in ['almenoUnGiornoDopo', 'subitoDopo', 'stessoGiorno', 'giornoDiverso', 'parallelo']
\end{lstlisting}   

\end{itemize}



\section{Sorgenti di dati}
Di seguito vengono introdotte tutte le sorgenti di dati da cui si sono ricavati i dati necessari ad un corretto funzionamento del software.
\subsection{Template Orario}\label{bookTemplateOrario}
Successivamente alla progettazione di alto livello del modello UML del Template Orario è stato implementato un modello di basso livello permettendo una rapida validazione delle differenti descrizioni degl Insegnamenti. Per la rappresentazione dei dati si è scelto il linguaggio XML\footnote{eXtensible Markup Language} per la sua struttura versatile e la possibilità di definire uno schema da rispettare rendendo la validazione dell'input immediata e visibile dai vari editor di testo disponibili sul mercato\footnote{Nello sviluppo della Tesi è stato usato di VisualCode.}.
Di seguito alcune parti del file \textit{schemaUseCase.xsd} contenente lo schema di validazione per i file XML contenenti i Template Orario in input al software.
\begin{itemize}
\item Catologo Template:
\begin{lstlisting}[language=XML,morekeywords={encoding,xs:schema,xs:element,xs:complexType,xs:sequence,xs:attribute}]
<xs:element name="CatalogoTemplate">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="TemplateOrario" minOccurs="1" maxOccurs="unbounded"></xs:element>
      </xs:sequence>
    </xs:complexType>
</xs:element>
\end{lstlisting}
Costituisce l'entità radice di un file XML valido. Permette di definire nello stesso file differenti Template Orario riguardanti quindi Insegnamenti diversi, tale scelta è dovuta al fatto che può capitare che in caso di istanza multiple di un Insegnamento, queste abbiano un elevato grado di affinità o che esista un Docente titolare di più di uno di essi; in questi casi la possibilità di avere una visione globale dei dati ne favorisce una corretta lettura e interpretazione.

\item Template Orario:
\begin{lstlisting}[language=XML,morekeywords={encoding,xs:schema,xs:element,xs:complexType,xs:sequence,xs:attribute},gobble=4]
    <xs:element name="TemplateOrario">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="id" minOccurs="1" maxOccurs="1"></xs:element>
                <xs:element name="ID_INC" type="xs:int" minOccurs="1" maxOccurs="1"></xs:element>
                <xs:element ref="NumIscritti" minOccurs="1" maxOccurs="1"></xs:element> <!-- se noto, altrimenti 0, verrà estratto dal GOF -->
                <xs:element ref="NumIscrittiPrimaFrequenza" minOccurs="0" maxOccurs="1"></xs:element> 
                <!-- se noto, altrimenti 0, verrà estratto dal GOF -->
                <xs:element ref="CapienzaAula" minOccurs="0" maxOccurs="1"></xs:element> <!-- se il Docente vuole specificare la capienza dell`Aula -->
                <xs:element ref="SlotScelto" minOccurs="0" maxOccurs="unbounded"></xs:element>
                <xs:element ref="SlotGenerico" minOccurs="0" maxOccurs="unbounded"></xs:element>
                <xs:element ref="Vincolo" minOccurs="0" maxOccurs="unbounded"></xs:element>
                <xs:element ref="Operatore" minOccurs="0" maxOccurs="unbounded"></xs:element>
                <xs:element name="Note" type="xs:string" minOccurs="0" maxOccurs="1"></xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
\end{lstlisting}
Rappresentazione omonima dell'entità nel modello XML; vengono introdotte le cardinalità degli attributi andando ad esplicitare quelli obbligatori, facoltativi o istanziabili con cardinalità multipla\footnote{Rispettivamente: \textit{minOccurs="1"}, \textit{minOccurs="1"} e \textit{maxOccurs="unbounded"}.}. Si evidenzia inoltre la presenza di degli elementi \textit{Vincolo} e \textit{Operatore} non introdotti esplicitamente nel modello UML che si occupano di modellare la relazione \textit{Vincolo\_in\_Slots} della rappresentazione di alto livello; infine non è presente alcun riferimento al tipo \textit{SlotScelto}\footnote{Questa scelta implementativa è dettata dall'impossibilità di un'implementazione efficace di tale entità senza andare ad inficiare il modello matematico. Si faccia riferimento al Capitolo \ref{chapModellazione} per ulteriori dettagli.}.
In seguito alla rimozione del tipo \textit{SlotPreferito} risulta essere superflua la classe SlotTemplate del modello UML se si procede istanziando all'interno di \textit{TemplateOrario} direttamente elementi di tipo \textit{SlotScelto} e \textit{SlotGenerico}.

\item Slot Scelto e Slot Generico:
\begin{lstlisting}[language=XML,morekeywords={encoding,xs:schema,xs:element,xs:complexType,xs:sequence,xs:attribute}]
   <xs:element name="SlotScelto">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="Docente" minOccurs="1" maxOccurs="unbounded"></xs:element>
        <xs:element ref="TipoErogazione" minOccurs="0" maxOccurs="1"></xs:element> <!-- default: Presenza-->
        <xs:element ref="NumSlotConsecutivi" minOccurs="1" maxOccurs="1"></xs:element>
        <xs:element ref="Tipo" minOccurs="1" maxOccurs="unbounded"></xs:element>
        <xs:element ref="NumIscritti" minOccurs="0" maxOccurs="1"></xs:element> <!-- Da inserire solo se diverso dal numero di iscritti all`Insegnamento -->
        <xs:element ref="Squadra" minOccurs="0" maxOccurs="1"></xs:element> <!-- default: no Squadra -->
        <xs:element ref="PreseElettriche" minOccurs="0" maxOccurs="1"></xs:element> <!-- default: no prese elettriche necessarie -->
        <xs:element ref="Locale" minOccurs="1" maxOccurs="1"></xs:element> <!-- default: Aula -->
        <xs:element ref="TipoScelta" minOccurs="0" maxOccurs="1"></xs:element> <!-- default: SlotPreciso -->
        <xs:element ref="Giorno"></xs:element> <!-- Indicano il giorno e l`ora in cui allocare lo Slot (in caso di NumSlotConsecutivi > 1 indicano il primo slot della lezione) -->
        <xs:element ref="FasciaOraria"></xs:element>
        <xs:element ref="Nota" minOccurs="0" maxOccurs="1"></xs:element>
      </xs:sequence>
      <xs:attribute name="slotId" type="xs:string" use="required"></xs:attribute>
    </xs:complexType>
  </xs:element>
  
    <xs:element name="SlotGenerico">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="Docente" minOccurs="1" maxOccurs="unbounded"></xs:element>
        <xs:element ref="TipoErogazione" minOccurs="0" maxOccurs="1"></xs:element> <!-- default: Presenza-->
        <xs:element ref="NumSlotConsecutivi" minOccurs="1" maxOccurs="1"></xs:element>
        <xs:element ref="Tipo" minOccurs="1" maxOccurs="unbounded"></xs:element>
        <xs:element ref="NumIscritti" minOccurs="0" maxOccurs="1"></xs:element> <!-- Da inserire solo se diverso dal numero di iscritti all`Insegnamento -->
        <xs:element ref="Squadra" minOccurs="0" maxOccurs="1"></xs:element> <!-- default: no Squadra -->
        <xs:element ref="PreseElettriche" minOccurs="0" maxOccurs="1"></xs:element> <!-- default: no prese elettriche necessarie -->
        <xs:element ref="Locale" minOccurs="0" maxOccurs="1"></xs:element> <!-- default: Aula -->
        <xs:element ref="Nota" minOccurs="0" maxOccurs="1"></xs:element>
      </xs:sequence>
      <xs:attribute name="slotId" type="xs:string" use="required"></xs:attribute>
    </xs:complexType>
  </xs:element>
\end{lstlisting}
Gli attributi presenti nel modello UML sono stati spostate in entrambe le entità figlie. Vengono prese le seguenti decisioni in fase implementativa circa la cardinalità e l'opzionabilità degli attributi:
\begin{itemize}
    \item\textit{Docente}: elemento obbligatorio e presente anche in più istanze poichè certi Slot potrebbero essere tenuti da più docenti contemporaneamente o più probabilmente in periodi diversi del semestre.
    \item\textit{NumSlotConsecutivi}, \textit{Tipo}, \textit{Locale}, \textit{Giorno} e \textit{FasciaOraria} sono elementi obbligatori.
    \item\textit{TipoErogazione}, \textit{NumIscritti}, \textit{Squadra}, \textit{PreseElettriche}, \textit{TipoScelta}\footnote{Inizialmente è stata prevista la possibilità di scegliere tra \textit{SlotPreciso}, \textit{NonPrima} e \textit{NonDopo}, successivamente si è preferito implementare un vincolo di questo genere a livello di Docente e/o Insegnamento piuttosto che di singolo Slot} e \textit{Nota}: questi elementi aggiungono solo informazioni supplementari; è previsto un valore di default conservativo\footnote{Si usa un approccio \say{Ask if you need} per allocare solamente le risorse strettamente necessarie, essendo queste in numero limitato.}.
    \item Attributo \textit{slotId}: obbligatorio per permettere di identificare in modo univoco l'elemento Slot tra tutti quelli del Template Orario\footnote{L'identificativo è globale ignorando se lo Slot corrente è di tipo \textit{SlotScelto} o di tipo \textit{SlotGenerico}.}. La distinzione univoca tra Slot è necessaria per una corretta definizione dei vincoli tra Slot.
\end{itemize}
 
 \item Vincolo
 \begin{lstlisting}[language=XML,morekeywords={encoding,xs:schema,xs:element,xs:complexType,xs:sequence,xs:attribute,xs:simpleType,xs:restriction,xs:enumeration}]
      <xs:element name="Vincolo">
    <xs:complexType>
      <xs:all>
        <xs:element ref="TipoVincolo"></xs:element>
        <xs:element name="slotId1" type="xs:string" minOccurs="1" maxOccurs="1"></xs:element>
        <xs:element name="slotId2" type="xs:string" minOccurs="1" maxOccurs="1"></xs:element>
        <xs:element ref="Penalita" minOccurs="0" maxOccurs="1"></xs:element> <!-- Viene omesso nel caso si tratti di parte di un Vincolo esterno -->
      </xs:all>
      <xs:attribute name="vincoloId" type="xs:string" use="required"></xs:attribute>
      <xs:attribute name="globalSlot1Id" type="xs:boolean" use="optional" default="false"></xs:attribute>
      <xs:attribute name="globalSlot2Id" type="xs:boolean" use="optional" default="false"></xs:attribute>
    </xs:complexType>
  </xs:element>
 \end{lstlisting}
 L'elemento rappresenta un vincolo elementare tra due elementi \textit{SlotGenerico} o \textit{SlotScelto} appartenenti al Template Orario. Gli elementi \textit{TipoVincolo} e \textit{Penalita} sono allineati con la loro progettazione di alto livello nel modello UML. In seguito a richieste particolari emerse in fase avanzata di sviluppo viene introdotta un'evolutiva per consentire la definizione di elementi \textit{Vincolo} che si riferiscono anche a Template Orario differenti tramite la definizione degli attributi opzionali \textit{globalSlot1Id} e \textit{globalSlot2Id} che permettono di collegare il vincolo non a due Slot del Template Orario corrente, ma a Slot qualsiasi presenti nell'intero dataset\footnote{L'evolutiva è una violazione del modello UML, tuttavia si è adottata per la semplicità di implementazione abbinata al numero limitato di modifiche che richiedeva.}.
 
 \item Operatore
 \begin{lstlisting}[language=XML,morekeywords={encoding,xs:schema,xs:element,xs:complexType,xs:sequence,xs:attribute,xs:simpleType,xs:restriction,xs:enumeration}]
      <xs:element name="Operatore">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="Vincolo" minOccurs="0" maxOccurs="unbounded"></xs:element>
        <xs:element ref="Operatore" minOccurs="0" maxOccurs="unbounded"></xs:element>
        <xs:element ref="Penalita" minOccurs="0" maxOccurs="1"></xs:element>        
      </xs:sequence>
      <xs:attribute name="id" type="TipoOperatore" use="required"></xs:attribute>
    </xs:complexType>
  </xs:element>
  
    <xs:simpleType name="TipoOperatore">
    <xs:restriction base="xs:string">
      <xs:enumeration value="OR"></xs:enumeration>
      <xs:enumeration value="AND"></xs:enumeration>
      <xs:enumeration value="NOT"></xs:enumeration>
    </xs:restriction>
  </xs:simpleType>
 \end{lstlisting}
 L'introduzione di questo nuovo elemento permette di superare le limitazioni presenti con il solo elemento Vincolo consentendo la definizione di vincoli costituiti da una logica booleana più complessa tramite l'annidamento di elementi Vincolo e Operatore all'interno di un Operatore radice\footnote{La penalità in questo caso assume valore solamente nell'elemento radice.}.
 \end{itemize}

 \begin{example}
\footnotesize
Viene presentato ora un esempio minimale di Template Orario che rispetta lo schema sinora descritto e che rispecchi fedelmente il caso d'uso seguente:
\begin{enumerate}
    \item\say{Il corso di Informatica presenta due diverse lezioni rispettivamente da 1.5h e 3h e un laboratorio articolato su due turni da 1.5h ciascuno da allocare consecutivamente}.
    \item\say{Le lezioni sono tenute solitamente dal docente Paolo Rossi, anche se saltuariamente la lezione da 1.5h è tenuta dal docente Marco Bianco. I laboratori sono gestiti entrambi da Francesco Neri.}
    \item\say{Il corso prevede 200 iscritti alla prima frequenza e si cerca di ripartire in modo uniforme gli studenti tra i due laboratori}.
    \item\say{Data la situazione incerta data dalla pandemia per una maggiore tutela degli studenti si decide di evitare l'uso dei laboratori universitari ma di utilizzare delle Aule con le prese elettriche in modo da permettere l'uso dei computer personali}.
    \item\say{\'E stabilito di non avere più di 3 ore di lezione lo stesso giorno e si desidera che i laboratori siano l'ultima lezione erogata nell'arco della settimana al fine di affrontare prima da un punto di vista teorico gli argomenti}.
    \item\say{Si vuole effettuare una lezione il Lunedì}.
\end{enumerate}
Di seguito la descrizione in XML dei requisiti:
\begin{lstlisting}[language=XML,morekeywords={encoding,xs:schema,xs:element,xs:complexType,xs:sequence,xs:attribute,xs:simpleType,xs:restriction,xs:enumeration,TemplateOrario,ID_INC,NumIscritti,SlotScelto,SlotGenerico,Docente,NumSlotConsecutivi,Tipo,Locale,Giorno,FasciaOraria,PreseElettriche,id,Vincolo,Penalita,slotId1,slotId2,TipoVincolo}]
<TemplateOrario>
<id>Informatica</id>
<ID_INC>11111</ID_INC>
<NumIscritti>200</NumIscritti>
<SlotScelto slotId="slot1"><Docente>Rossi Paolo</Docente><NumSlotConsecutivi>2</NumSlotConsecutivi><Tipo>L</Tipo><Locale>Aula</Locale><Giorno>Lun</Giorno><FasciaOraria>Indifferente</FasciaOraria></SlotScelto>
<SlotGenerico slotId="slot2"><Docente>Rossi Paolo</Docente><Docente>Marco Bianco</Docente><NumSlotConsecutivi>1</NumSlotConsecutivi><Tipo>L</Tipo><Locale>Aula</Locale></SlotGenerico>
<SlotGenerico slotId="slotLab"><Docente>Neri Francesco</Docente><NumSlotConsecutivi>2</NumSlotConsecutivi><Tipo>EA</Tipo><NumIscritti>100</NumIscritti><PreseElettriche>Si</PreseElettriche><Locale>Aula attrezzata CA2</Locale></SlotGenerico>

<Vincolo vincoloId="vinc1"><Penalita>LVH</Penalita><slotId1>slotLab</slotId1><slotId2>slot1</slotId2><TipoVincolo>almenoUnGiornoDopo</TipoVincolo></Vincolo>
<Vincolo vincoloId="vinc2"><Penalita>LVH</Penalita><slotId1>slotLab</slotId1><slotId2>slot2</slotId2><TipoVincolo>almenoUnGiornoDopo</TipoVincolo></Vincolo>
<Vincolo vincoloId="vinc3"><Penalita>LVH</Penalita><slotId1>slot1</slotId1><slotId2>slot2</slotId2><TipoVincolo>giornoDiverso</TipoVincolo></Vincolo>
</TemplateOrario>
\end{lstlisting}
\end{example}
 
\subsection{Aule disponibili}\label{bookLocaliXmlSchema}
Un'ulteriore fonte di informazioni essenziale per il software sono i Locali resi disponibili dall'università per allocare gli Slot. Al fine di uniformare le sorgenti di informazioni e di evitare il verificarsi di ambiguità è presente un ulteriore schema per validare i file rappresentanti i Locali allocabili. Di seguito alcuni dei cardini di tale modello:
\begin{itemize}
    \item Locali Allocati e Gruppo di Locali
    \begin{lstlisting}[language=XML,morekeywords={encoding,xs:schema,xs:element,xs:complexType,xs:sequence,xs:attribute,xs:simpleType,xs:restriction,xs:enumeration}]
    <xs:element name="LocaliAllocati">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="GruppoLocali" minOccurs="1" maxOccurs="unbounded"></xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    
    <xs:element name="GruppoLocali"> 
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="Nome"></xs:element>
                <xs:element ref="Locale"></xs:element>
                <xs:element ref="Capienza"></xs:element>
                <xs:element ref="PreseElettriche"></xs:element>
                <xs:element ref="Quantita"></xs:element>
                <xs:element ref="Da"></xs:element>
                <xs:element ref="A"></xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    \end{lstlisting}
I Locali Allocati sono un elenco di Gruppi di Locali, in cui ognuno di questi rappresenta la disponibilità di un certo numero di Locali di uno stesso tipo (ed eventualmente di una data capienza) in un arco temporaneo in quanto non è garantito che i Locali liberi possano mantenersi gli stessi per tutta la settimana.
\item Locali
\begin{lstlisting}[language=XML,morekeywords={encoding,xs:schema,xs:element,xs:complexType,xs:sequence,xs:attribute,xs:simpleType,xs:restriction,xs:enumeration}]
    <xs:element name="Locale">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="Aula multimediale"></xs:enumeration>
            <xs:enumeration value="Aula"></xs:enumeration> <!-- Default value -->
            <xs:enumeration value="Aula attrezzata"></xs:enumeration>
            <xs:enumeration value="Laboratorio"></xs:enumeration> <!-- Tutti i lab vanno bene -->
            <xs:enumeration value="LABINF"></xs:enumeration>
            <xs:enumeration value="LAIB"></xs:enumeration>
            <xs:enumeration value="LADISPE"></xs:enumeration>
            <xs:enumeration value="LED"></xs:enumeration>
            <xs:enumeration value="LED1"></xs:enumeration> <!-- LED1 e LED2 da trattati come il LABINF -->
            <xs:enumeration value="LED2"></xs:enumeration>
            <xs:enumeration value="ACSLAB"></xs:enumeration>
            <xs:enumeration value="Aula 5T"></xs:enumeration>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
\end{lstlisting}
Una lettura approfondita delle tipologie di locali da selezionare fa saltare all'occhio la mancanza dei valori: \textit{Aula attrezzata CA2}, \textit{Aual attrezzata CA}, \textit{Aula TableBox} e \textit{Aula Wallbox}. Si considerano tutti i casi elencati appartenenti al tipo generico Aula\footnote{Si tratta di una scelta implementativa resasi necessaria per raggiungere un compromesso tra precisione del modello e performance del software.}, restando fermo il fatto che l'abbinamento di uno Slot in un locale di tipo {Aula} o derivati possa avvenire solamente se resta rispettato il vincolo sulle presenza di prese elettriche (se richiesto) e se la capienza dell'aula è congrua al numero di studenti o eventualmente superiore\footnote{Funzionalità opzionale attivabile in sede di configurazione del software. Fare riferimento al manuale utente.}.
\end{itemize}

\begin{example}\label{esAuleXML}
\footnotesize
Di seguito un esempio elementare per definire la seguente disponibilità di Locali:
\begin{lstlisting}[language=XML,morekeywords={encoding,xs:schema,xs:element,xs:complexType,xs:sequence,xs:attribute,xs:simpleType,xs:restriction,xs:enumeration,LocaliAllocati,GruppoLocali,Nome,Locale,Capienza,PreseElettriche,Quantita,Da,A,Giorno,FasciaOraria}]
<LocaliAllocati xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../models/schemaAule.xsd">
    <GruppoLocali>
        <Nome>Aule piccole</Nome>
        <Locale>Aula</Locale>        
        <Capienza>Piccola</Capienza>
        <PreseElettriche>Si</PreseElettriche>
        <Quantita>2</Quantita>
        <Da>
            <Giorno>Lun</Giorno>
            <FasciaOraria>8.30-10.00</FasciaOraria>
        </Da>
        <A>
            <Giorno>Mar</Giorno>
            <FasciaOraria>17.30-19.00</FasciaOraria>
        </A>
    </GruppoLocali>  
    <GruppoLocali>
        <Nome>Aule piccole</Nome>
        <Locale>Aula</Locale>        
        <Capienza>Piccola</Capienza>
        <PreseElettriche>Si</PreseElettriche>
        <Quantita>2</Quantita>
        <Da>
            <Giorno>Mer</Giorno>
            <FasciaOraria>8.30-10.00</FasciaOraria>
        </Da>
        <A>
            <Giorno>Ven</Giorno>
            <FasciaOraria>17.30-19.00</FasciaOraria>
        </A>
    </GruppoLocali>
    <GruppoLocali>
        <Nome>LED</Nome>
        <Locale>LED</Locale>
        <Capienza>NonDisponibile</Capienza>
        <Quantita>4</Quantita>
        <Da>
            <Giorno>Lun</Giorno>
            <FasciaOraria>8.30-10.00</FasciaOraria>
        </Da>
        <A>
            <Giorno>Ven</Giorno>
            <FasciaOraria>17.30-19.00</FasciaOraria>
        </A>
    </GruppoLocali>
</LocaliAllocati>
\end{lstlisting}
\end{example}


\subsection{Richieste Docenti}
Dai requisiti del software è evidente la varietà di vincoli che i Docenti possono esprimere e di cui è necessario tenere conto per ottenere una soluzione. Si è deciso di rappresentare tutti i vincoli esprimibili dai Docenti sotto forma di file JSON, di cui ora verranno evidenziate le tipologie preferenze espresse:
   
\begin{example}\label{esPreferenzeDocenti}
\footnotesize
Preferenza di giorni e fasce orarie in cui devono svolgersi gli Slot di un Insegnamento (\textit{insegnamenti.json}).
 \begin{lstlisting}[language=json,firstnumber=1]
{
    "preferenze": {
        "11111": {
            "favorevole": {
                "Lun_16.00-17.30_LV5": "primaDi"
            },
            "contrario": {
                "Lun_8.30-10.00_LV2": "ugualeA",
                "Lun_17.30-19.00_LVH": "ugualeA",
                "Indifferente_16.00-17.30_LV3": "dopoDi"
            }
        }
    }
}
\end{lstlisting}
\end{example}
Nell'Esempio \ref{esPreferenzeDocenti} vengono definiti per ogni Insegnamento un elenco di pareri favorevoli e/o contrari e ognuno di essi viene abbinato ad uno slot temporale, ad un livello di penalità e ad un vincolo di logica temporale\footnote{Le logiche temporali ammesse nel modello sono: \textit{primaDi}, \textit{ugualeA} e \textit{dopoDi}.}.
\begin{example}\label{esPreferenzeDocentiGen}
\footnotesize
Preferenza di un Docente a tenere e/o non tenere lezione in determinati giorni e/o fasce orarie (\textit{docenti.json}).
 \begin{lstlisting}[language=json,firstnumber=1]
{
    "preferenze": {
        "Francesco Neri": {
            "favorevole": {
                "Lun_16.00-17.30_LV1": "primaDi"
            },
            "contrario": {
                "Lun_8.30-10.00_LV0": "ugualeA",
                "Lun_17.30-19.00_LV0": "ugualeA"
            }
        },
    }
} 
 \end{lstlisting}
\end{example}

Nell'Esempio \ref{esPreferenzeDocentiGen} vengono definiti per ogni Docente un elenco di pareri favorevoli e/o contrari e ognuno di essi viene abbinato ad uno slot temporale, ad un livello di penalità e ad un vincolo di logica temporale\footnote{Le logiche temporali ammesse nel modello sono: \textit{primaDi}, \textit{ugualeA} e \textit{dopoDi}.}.
   
\begin{example}\label{esLimitiGiornalieriDocenti}
\footnotesize
Numero massimo di ore di lezione allocate quotidianamente per un singolo Docente (\textit{docenti.json}).
 \begin{lstlisting}[language=json,firstnumber=1]
{
    "Docenti": {
        "maxSlotPerDay": {
            "default": 4,
            "Francesco Neri": 5
        },
    }
}
\end{lstlisting}
\end{example}
Viene definito come vincolo generale un massimo di 4 slot orari\footnote{6 ore.} come limite di lezioni tenute da un Docente in un dato giorno. Tale limite è tuttavia personalizzabile per il singolo Docente in caso di particolari richieste come mostrato nell'Esempio \ref{esLimitiGiornalieriDocenti}.    
   
\begin{example}\label{esInsSovrapponibili}
\footnotesize
Indicazione su Insegnamenti sovrapponibili anche se tenuti dallo stesso Docente\footnote{Si tratta di un caso particolare in cui un Docente tiene lezioni in Insegnamenti differenti in periodi diversi del semestre e che quindi non devono risultare in conflitto tra loro.}.
\begin{lstlisting}[language=json,firstnumber=1]
 {
    "Docenti": {
        "insegnamentiSovrapponibili":{
            "Francesco Neri":[254394,254395,254396]
        },
    }
}
 \end{lstlisting}
\end{example}

\begin{example}\label{esAnnoPrecedente}
\footnotesize
Preferenza di un Docente ad utilizzare l'orario dell'anno precedente (\textit{docenti.json}).
\begin{lstlisting}[language=json,firstnumber=1]
{
    "Docenti": {
        "preferenzaAnnoPrecedente": {
            "Francesco Neri": "prova1_LV2"
        },
    }
} 
 \end{lstlisting}
\end{example}
Nell'esempio \ref{esAnnoPrecedente} tutti gli Slot associati al Docente indicato nel piano di allocazione specificato ("prova1" in questo caso) saranno allocati tenendo conto dell'allocazione precedente e andando incontro alla penalità specificata in caso non vengano rispettati.

\begin{example}\label{esVincoliVariDocente}
\footnotesize
Distanza minima/massima tra Slot tenuti dallo stesso Docente  se allocati lo stesso giorno ed eventuale penalità in caso questi Slot appartengano ad Insegnamenti differenti (\textit{docenti.json}).
\begin{lstlisting}[language=json,firstnumber=1]
 {
    "Docenti": {
        "distanzaMinima": {
            "Francesco Neri": "1_LV1"
        },
        "distanzaMassima": {
            "Francesco Neri": "1_LV2"
        },
        "insegnamentiDiversiSameDay": {
            "Francesco Neri": "LV1"
        }
    }
} 
\end{lstlisting}
\end{example}
Nell'Esempio \ref{esVincoliVariDocente} sono presenti preferenze riguardanti la distanza minima e massima il numero intero concatenato al livello di penalità con un \say{\_} corrisponde al numero di slot orari di distanza.

Tutte le tipologie di vincolo illustrate in questa sezione di default non sono attive, ma devono essere esplicitate nei file JSON indicati dagli esempi.



\subsection{Insegnamenti in un Orientamento}\label{bookInsegnamentiInOrientamento}
La descrizione di tutti gli Orientamenti e i CDL in cui compare un Insegnamento è un'ulteriore fonte di dati per il software. Essi vengono salvati all'interno di un database di appoggio seguendo la progettazione UML di Figura~\ref{fig:UML_insegnamento}.

\begin{figure}[tb]
    \centering
    \includegraphics[width=.7\textwidth]{images/figures/db Insegnamento in Orientamento.png}
    \caption{Modello logico Insegnamento in Orientamento.}
    \label{fig:Modello_logico_Insegnamento_in_Orientamento}
\end{figure}

Il modello logico dell'Orientamento di Figura~\ref{fig:Modello_logico_Insegnamento_in_Orientamento} prevede anche l'adozione di un nuovo attributo \textit{alfabetica} poichè è necessario non generare vincoli tra Insegnamenti appartenenti ad alfabetiche differenti\footnote{Fissato un Orientamento in cui sono presenti due istanze di Insegnamenti distinguibili tra loro per una diversa valorizzazione dell'attributo alfabetica, sarebbe scorretto impedire in assenza di vincoli di natura differente l'allocazione parallela di Insegnamenti anche obbligatori per tale Orientamento se appartenenti a differenti alfabetiche.}.




\section{Formato soluzione}
Il tool durante la sua esecuzione salva le soluzioni all'interno del database secondo la progettazione UML di Figura \ref{fig:UML_slot_insegnamento}. Il modello logico dello Slot rispecchia la progettazione di alto livello a meno di un ulteriore attributo note inserito per consentire di aggiungere del testo che potrebbe rivelarsi utile in una fase successiva all'export della soluzione nel caso di necessità particolari per lo Slot\footnote{Tale campo viene esportato in output come spiegato nella Sezione \ref{bookEsport}.} come mostrato nel modello logico dello Slot in Figura~\ref{fig:modelloLogicoSlot}.

\begin{figure}
    \centering
    \includegraphics[width=.85\textwidth]{images/figures/db Slot.png}
    \caption{Modello logico Slot.}
    \label{fig:modelloLogicoSlot}
\end{figure}
