Introduzione

Il lavoro di tesi punterà a generare in maniera automatica (o semi-automatica) il modello di simulazione descritto da programmi java che utilizzano la libreria MASON (http://cs.gmu.edu/~eclab/projects/mason/). Per la generazione della documentazione verrà utilizzato DOXYGEN (http://www.stack.nl/~dimitri/doxygen/).

Diario

  • Per iniziare ho dato una prima lettura al manuale MASON (http://cs.gmu.edu/~eclab/projects/mason/manual.pdf) per comprendere il funzionamento della libreria. Ho quindi familiarizzato con la libreria scrivendo un semplice programma di simulazione. Successivamente ho installato e iniziato a testare "doxygen" su windows.
  • Successivamente ho studiato il manuale di doxygen, individuando le caratteristiche che potevano essere utili per documentare il modello di simulazione riportato nel codice. Tra le potenzialità di doxygen è risultato interessante poter creare delle pagine dedicate nella documentazione riportanti le informazioni desiderate. Ciò è possibile creando dei gruppi di entità (package, classi, variabili ecc) o creando un file di markdown con la sintassi opportuna. Ho quindi approfondito il codice di uno degli esempi forniti con MASON, "AntsForage".
  • Commentato il codice "AntsForage" per cercare di ricavare una pagina dedicata descrivente il modello di simulazione. Estratta documentazione tramite doxygen in formato pdf. Individuata libreria java ("javaparser") per navigare/modificare sorgenti java (https://github.com/matozoid/javaparser).
  • Studio di alcuni paper riguardanti modelli di simulazione e documentazione di modelli di siumlazione (https://peerj.com/preprints/273/ - http://www.sciencedirect.com/science/article/pii/S0304380014000611 - http://bio.uib.no/te/papers/Grimm_2010_The_ODD_protocol_.pdf). Di particolare utilita' il protocollo ODD (Overview, Design concepts and Details) che fornisce delle linee guida riguardo la documentazione di ABMs (agent-based models). In particolare propone alcune domande guida che possiamo porci per documentare un ABMs. Risulta fondamentale capire quali delle domande possono essere risposte in maniera automatica e quali chiedendo input all'utente.
  • Sono entrato nel vivo della questione iniziando a realizzare un plugin di export per eclipse. Lo scopo del plugin è quindi quello di ricavare, dato un progetto che utilizza MASON, informazioni semantiche dal codice relative al modello di simulazione descritto dall'applicazione. Iniziata la fase di implementazione è stata presto abbandonata la libreria "javaparser" ed è stato introdotto il framework AST di Eclipse(http://www.eclipse.org/articles/article.php?file=Article-JavaCodeManipulation_AST/index.html). Il progetto è consultabile qui: "https://code.google.com/p/masonhelperdocumentation/".

Prima versione

E' stata realizzata una prima versione del plugin. Ciò che è emerso dalla prima versione è che le informazioni non risultavano strutturate in maniera ragionevole. Diventava quindi faticoso individuare le informazioni nella documentazione generata. L'obiettivo posto quindi è stato quello di riorganizzare il wizard in maniera tale da ottenere una documentazione strutturata secondo lo standard ODD. Ho iniziato quindi a lavorare alla seconda versione dell'applicazione.

Seconda versione

La seconda versione del plugin mira a riorganizzare la documentazione ed a correggere alcuni problemi implementativi della prima.

Parsing del codice

La prima versione presentava alcuni punti deboli per la parte di parsing del codice. Ad esempio la ricerca delle informazioni sui fields della simulazione era fatta nel seguente modo:

  • Partendo dall'oggetto “FieldDeclaration” sul quale invocavo “getInitializer” che restituiva la stringa di inizializzazione (“es: new Grid(a, b,c ))
  • Su tale stringa eseguivo uno split con parametro “;” e assumevo che il risultato fosse “a,b,c”. Si cercavano quindi a,b e c nella classe per ricavare ulteriori informazioni

Il problema capita quando abbiamo una inizializzazione del tipo: balls = new Continuous3D(collisionDistance, gridWidth,gridHeight,gridLength); dove lo split avrebbe dato stringhe "collisionDistance", " gridWidth" (nota lo spazio iniziale " gridWidth"). La ricerca di tali stringhe tra le variabili della classe non avrebbe restituito risultato per "gridWidth". Utilizzando il visitor pattern di ast ho realizzato l'oggetto "FieldDeclarationVisitor" che visita la "compilationUnit" data come parametro implicito "visitando" gli "Assignment"; trovato il node Assignment istanza di "ClassInstanceCreation" e con nome uguale alla field che cerchiamo, si estrae la lista di parametri con "arguments()".

Iterabilità

Altro problema è legato all'iterabilità del processo di autogenerazione della documentazione. Il problema da risolvere è quello di mostrare le informazioni già inserite dall'utente in altri utilizzi del wizard. Tale operazione era fatta (nella prima versione) estraendo il commento presente su un campo come stringa. A questo punto veniva rigenerato il commento automatico e veniva confrontato con il vecchio commento; se questi coincidevano veniva lasciato solo il commento automatico altrimenti veniva mostrata la parte differente nella casella di input dell'utente e la parte autogenerata nella sezione opportuna. Questo causava alcuni problemi in quanto ci troviamo a che fare con stringhe e quindi anche un solo spazio in più/meno poteva portare a fallimenti durante il confronto. La strada intrapresa è quella di raccogliere le informazioni generate durante il wizard in un oggetto “ODD” e serializzare tale oggetto alla fine del wizard. In questo modo in utilizzi diversi del wizard le informazioni eventualmente già inserite vengono recuperate dall'oggetto serializzato. L'introduzione di un oggetto "ODD" contenente tutte le informazioni sul wizard ci slega dall'utilizzo di doxygen; avendo tale oggetto potremo decidere di scrivere le informazioni raccolte in altri formati (che non siano quindi solo i commenti in stile doxygen).

Process overview and scheduling

La fase di process overview and scheduling di ODD è legata alla fase Submodels. Ciò che lega queste due fasi è che la prima riepiloga le azioni svolte dalle entità; la seconda approfondisce tali azioni. Tale legame deve essere risolto anche in fase di implementazione. A tale scopo durante la fase di process overview and scheduling vengono "visitati" i metodi "start" e "step" della "SimState" e degli agenti. Durante la "visita" vengono appuntate le "MethodInvocations". L'idea è che laddove il programmatore crea un metodo, questo deve rappresentare un'azione separata (un submodels). Durante la fase di Submodels verranno recuperate tali invocazioni e verranno "visitate" in maniera dettagliata.

Colors feature

Aggiunta possibilità di settare diversi colori per i commenti autogenerati e quelli inseriti in input dall'utente. Per implementare questa funzionalità è stato aggiunto un tag "" intorno ai commenti. Uno dei problemi riscontrati durante questa fase è stato che “doxygen” interpretava il tag in modo da renderlo visibile:

 diventava -> &lt.span

Per risolvere tale problematica "doxygen" mette a disposizione le sequenze di escape:

/htmlonly /endhtmlonly

Quindi ho racchiuso il tag "<span>" all'interno delle sequenze di escape di “doxygen”.

Terza versione

La seconda versione sviluppata prometteva un semplice riutilizzo dell’applicazione realizzando un’output svincolato da doxygen (vedi paragrafo “iterabilità”).
Per confermare questa tesi è stata sviluppata una terza versione del plug-in che aggiunge altre 2 modalità di output:

  • Pdf
  • Txt

Quindi in totale avremo le seguenti modalità di ouput: Doxygen, pdf e txt. Per raggiungere tale obiettivo ho realizzato un oggetto di supporto all’oggetto “ODD” già creato che si occupa solamente di estrarre il contenuto delle 7 sezioni di ODD sottoforma di Stringa.
La libreria “itext” ha supportato la creazione del documento pdf.

Aggiornamenti 12-07-2014

Eliminazione-backup commenti autogenerati

Alla ne della procedura guidata il plugin genera quindi una serie di commenti al codice in stile Doxygen. Tali commenti intaccano la pulizia del codice. Per risolvere tale problema, alla ne della procedura i commenti
generati dal plugin vengono eliminati ed il codice ritorna allo stato iniziale.
E' stata introdotta quindi una firma nei commenti in modo tale da poterli riconoscere ed eliminarli alla fine lasciando eventuali commenti inseriti dall'utente.
La classe "JavaDocVisitor" si occupa proprio di visitare una "CompilationUnit" e, incontrato un nodo di tipo "Javadoc node", se questo contiene la firma del plugin, lo elimina.
E' tuttavia possibile conservare una copia di backup del codice contenente i commenti generati in automatico spuntando la casella 'Save backup of commented code' nell'ultima pagina del wizard. Verrà creata una cartella nella directory contenente le copie dei fi les sorgenti con estensione ._MAD(MAD(Mason assisted documentation è il nome del plugin).

Rtf

Aggiunto il supporto per output di tipo rtf. Tale funzionalità è stata ottenuta utilizzando la libreria "iText".

Conclusioni

Possiamo a questo punto trarre delle conclusioni sul lavoro svolto. Riprendiamo da quello che era l'obiettivo iniziale: 'Documentare programmi di simulazione multi-agente scritti in java con libreria MASON'. Il prodotto
realizzato e descritto in questo lavoro di tesi produce un risultato esaustivo rispetto all'obiettivo iniziale. Il plugin realizzato supporta l'utente durante la creazione della documentazione per un programma di simulazione multiagente, generando documentazione che non da la sensazione di un qualcosa di generato in maniera automatica. L'output racconta quello che e il modello di simulazione, generando in alcuni punti un discorso in linguaggio naturale che rende l'idea di quello che avviene nel modello. Inoltre la struttura dell'output segue uno standard noto(protocollo ODD) agevolando la di ffusione di tale standard. Utilizzando il plugin si può uniformare la struttura delle documentazioni di ABMs scritti in java con libreria MASON. L'esperto del modello potrà così abituarsi ad uno standard che ritroverà in tutte le documentazioni; il programmatore non dovrà preoccuparsi di strutturare la documentazione, ma dovrà solo contribuire alla raccolta di informazioni e ffettuata dal wizard.

Seminari