Introduction to automatic ABMs documentation

1. Introduction to automaticABMsdocumentation Keywords: Doxygen ODD protocol MASON documentation Simone Romano

2. Cosa vedremo: • Panoramica modelli di simulazione basati sugli agenti - MASON • Doxygen • Può aiutarci? • ODD Protocole MASON • Doxygen e ODD protocol • Semanticanalysis of MASON code • AbstractSyntaxTree Automatic ABMs documentation - Simone Romano

3. Panoramica modelli di simulazione basati sugli agenti - MASON • Doxygen • Può aiutarci? • ODD Protocole MASON • Doxygen e ODD protocol • Semanticanalysis of MASON code • AbstractSyntaxTree Automatic ABMs documentation - Simone Romano

4. Sistemi multi-agente • Branca relativamente nuova dell’informatica: • Primi studi: anni ‘80 • Diffusione: circa metà anni ‘90 • Interessante tipologia di modellazione di società, ed hanno a questo riguardo vasti campi d'applicazione, che si estendono fino alle scienze umane e sociali (economia, sociologia, etc.). • STRUTTURA • Agenti (entità autonoma) • Ambiente Automatic ABMs documentation - Simone Romano

5. MASON “MASON is a fast discrete-event multiagent simulation library core in Java” STRUTTURA • Agenti - Steppable • Ambiente - SimState OBIETTIVO: Generazioneautomatica (o semi-automatica) di documentazione di programmiscritti in java cheutilizzano MASON. VOGLIAMO DOCUMENTARE: • Struttura del programma • Semantica del programma Automatic ABMs documentation - Simone Romano

6. Panoramica modelli di simulazione basati sugli agenti - MASON • Doxygen • Può aiutarci? • ODD Protocole MASON • Doxygen e ODD protocol • Semanticanalysis of MASON code • AbstractSyntaxTree Automatic ABMs documentation - Simone Romano

7. Doxygenis the de facto standard tool for generatingdocumentation from annotated C++ sources, butitalsosupportsotherpopularprogramminglanguagessuchas C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOfficeflavors), Fortran, VHDL, Tcl, and to some extent D. • Multipiattaforma • Linux - MAC OS - Windows • Configurabile • File di configurazione AutomaticABMsdocumentation - Simone Romano

8. Utilizzo di doxygen PASSI: • Creazione file di configurazione • Esecuzione di doxygen CREAZIONE FILE DI CONFIGURAZIONE • Tramite shell lanciando il comando doxygen –g • Tramite applicazione dedicata • Plug-in per eclipse, ECLOX ESECUZIONE • doxygenpathFileConfig Per tutti i test fatti è stata usato invocato doxygen da terminale; questo perché l’idea è stata da subito quella di realizzare un’applicazione esterna che sfruttasse in maniera mirata alcune caratteristiche di doxygen. • OUTPUT: • LATEX • HTML • PDF Automatic ABMs documentation - Simone Romano

9. File di configurazione Caratteristiche principali • INPUT • OUTPUT_DIRECTORY • PROJECT_NAME • INLINE_SOURCES • REFERENCED_BY_RELATION If the REFERENCED_BY_RELATION tag is set to YES then for each documented functionall documented functions referencing it will be listed. The default value is: NO. • REFERENCES_RELATION If the REFERENCES_RELATION tag is set to YES then for each documented function all documented entities called/used by that function will be listed. The default value is: NO. • HTML_HEADER • HTML_FOOTER • GENERATE_TREEVIEW • OUTPUT_LANGUAGE • INLINE_GROUPED_CLASSES (*) Automatic ABMs documentation - Simone Romano

10. File di configurazione - grafici Necessità di Graphvizhttp://www.graphviz.org/ • HAVE_DOT = YES • DOT_PATH • DOT_NUM_THREADS • CLASS_GRAPH Automatic ABMs documentation - Simone Romano

11. File di configurazione - grafici • CALLER_GRAPH • CALL_GRAPH Automatic ABMs documentation - Simone Romano

12. Commenti al codice Diversi stili • Javadoc Style: /** * Commenthere */ Possiamo commentare • Package • Classi • Metodi • Parametri • Parametri di metodi • Voidfoo(int v /**<[in] doescomment for v.*/) Immagini \image html pathImg Automatic ABMs documentation - Simone Romano

13. Moduli • Possiamo creare dei moduli (pagine dedicate nella documentazione) • Utilità? Raggruppare informazioni semanticamente collegate strutturando la documentazione secondo le nostre esigenze. Automatic ABMs documentation - Simone Romano

14. Creazione moduli • Per generare moduli bisogna definirli con la sintassi • @defgroupGroupName Brief Description • Sarà ora possibile aggiungere elementi del codice al gruppo con la sintassi • @ingroupGroupName posto sull’entità da documentare • E’ possibile creare gruppi in altri gruppi: /** * @defgroup Field * @ingroupSimulationModel */ • Tornando al file di configurazione • (*) INLINE_GROUPED_CLASSES include le informazioni delle classi appartenenti al gruppo all’interno del gruppo stesso. Automatic ABMs documentation - Simone Romano

15. Automatic ABMs documentation - Simone Romano

16. Ci può aiutare Doxygen? • Ricordo che lo scopo di questo lavoro di tesi è generare in maniera automatica (o semi-automatica) documentazione di modelli di simulazione multi-agente che utilizzano la libreria MASON. • La documentazione dovrà avere una struttura ben precisa • Doxygen ci autogenera la documentazione della struttura del codice (relazioni tra classi, struttura del progetto, struttura di ogni classe) • Per quanto sia configurabile, non ho trovato impostazioni del tipo: EXTRACT_SIMULATION_MODEL = YES nel file di configurazione • Possiamo però strutturare la documentazione in maniera personalizzata, utilizzando in particolare i MODULI e creando delle sezioni che racchiudono le informazioni inerenti il modello di simulazione. Automatic ABMs documentation - Simone Romano

17. Qual è il problema? • Ecologisti e scienziati sociali sono stati a lungo di fronte alla sfida di come modellare la complessità di molti sistemi reali. • AMBs è uno degli approcci • Individui eterogenei • Diversa interazione tra diversi individui • Capacità degli individui di adattarsi all’ambiente • Documentazione spesso povera o non strutturata • Non possiamo valutare il modello Automatic ABMs documentation - Simone Romano

18. Panoramica modelli di simulazione basati sugli agenti - MASON • Doxygen • Può aiutarci? • ODD Protocole MASON • Doxygen e ODD protocol • Semanticanalysis of MASON code • AbstractSyntaxTree Automatic ABMs documentation - Simone Romano

19. ODD Protocol(Overview, Design concepts and Details)Come documentare un ABMs (agent-basedmodels) Pubblicato nel 2006 per standardizzare le descrizioni di ABMs (modelli basati sugli agenti). • Volker Grimm - Helmholtz Centre for EnvironmentalResearch-UFZ, Department of EcologicalModelling, Permoserstr. 15, 04318 Leipzig, Germany • Uta Berger - Institute of Forest Growth and Computer Science, Dresden University of Technology, P.O. 1117, 01735 Tharandt, Germany • Donald L. DeAngelis- USGS/Biological Resources Division and Dept. of Biology, University of Miami, PO Box 249118, Coral Gables, FL 33124, USA • J. Gary Polhill - Macaulay Land Use Research Institute, Craigiebuckler, Aberdeen, AB15 8QH, United Kingdom • JarlGiske-University of Bergen, Department of Biology, P.O. Box 7803, N-5020 Bergen, Norway • Steven F. Railsbackf - Department of Mathematics, Humboldt State University, Arcata, CA 95521, USA, - Lang, Railsback & Associates, 250 California Avenue, Arcata, CA 95521, USA Automatic ABMs documentation - Simone Romano

20. Scopo • Semplificare e rendere efficienti i processi di • Descrizione di modelli • Lettura di modelli Osservazioni • Può guidare anche in fase di FORMULAZIONE di modelli. • questo perché offre una sorta di checklistcon le caratteristiche principali da descrivere in un modello. Automatic ABMs documentation - Simone Romano

21. Elementi del protocollo ODD • Purpose • State variables and scales • Processoverview and scheduling • Design concepts • Emergence • Adaption • Fitness • Prediction • Sensing • Interaction • Stochasticity • Collectives • Observation • Initialization • Input • Submodels Quandoilprotocollo ODD vieneusato per documentare un ABMs, questovàscrittoespicitamentenelladocumentazione: “the model description follows the ODD (Overview, Design concepts, Details) protocol (Grimm et al., 2006, this work)”. Automatic ABMs documentation - Simone Romano

22. 1)Purpose QUESTION • Whatis the purpose of the model? • E’ importante non aggiungere dettagli sul funzionamento del modello a questo livello di documentazione. MASON Non possiamo rispondere in maniera automatica a questa domanda. Automatic ABMs documentation - Simone Romano

23. 2)Entities, state variables, and scales QUESTION • What kinds of entities are in the model? • By what state variables, or attributes, are these entities characterized? • What are the temporal and spatial resolutions and extents of the model? Un’entità è un attore/oggetto distinto che si comporta come un’unità indipendente • Interagisce con altre entità • È influenzato dall’ambiente che lo circonda • Caratterizzata da uno stato AutomaticABMsdocumentation - Simone Romano

24. 2)Entities, state variables, and scales • Agents/individuals • Spatialunits(es. gridcells) • In genere danno informazioni sullo stato di un agente (posizione) • In alcuni sistemi degli agenti possono essere modellati come caratteristica di una cella (es. umidità del suolo) • Environment • Scales • Dare un’unità di misura a tempo e spazio Automatic ABMs documentation - Simone Romano

25. 2)Entities, state variables, and scales MASON Possiamorispondere (in parte) in maniera automatica. • Agents/individuals • Steppable • Spatialunits (es. gridcells) Environment • SimState • Scales • Riusciamo a ricavare che le dimensioni della griglia principale sono WIDTH*HEIGTH • Riusciamo a ricavare che WIDTH vale x ed HEIGHT vale y • Che x ed y rappresentano chilometri, metri, miglia…NO • Definire entità e variabili di stato • Stoppare l’esecuzione in un istante t e salvare le informazioni dello stato corrente • Rilanciare l’esecuzione e prelevare le informazioni sul nuovo stato. Automatic ABMs documentation - Simone Romano

26. 3) Processoverview and scheduling QUESTION • Who (i.e., what entity) does what, and in what order? • Non scendereneidettagli ma elencareunalistadelleazionisvoltedalleentità; ciascuna di questeazionipuòessereapprofonditanellasezioneSUBMODELS • When are state variables updated? MASON Possiamorispondere a queste domande in maniera automatica. • Who (i.e., what entity) does what, and in what order? • “schedule.scheduleRepeating” dàinformazionisu come verrannoschedulatigliagenti • When are state variables updated? • Per ogni agente, il metodo «step» dà informazioni riguardo la sequenza di azioni effettuate dall’agente ad ogni step. Automatic ABMs documentation - Simone Romano

27. 4)Design concepts • Basic Principles: in questa sezione vanno inseriti i concetti di base che regolano la simulazione, le ipotesi, l’evoluzione della complessità. • Emergence: quali sono le chiavi emergenti del modello? • Adaption: in che maniera gli agenti prendono decisioni? • Learning: alcuni agenti cambiano il loro comportamento nel tempo in base alla loro esperienza • Prediction: in base alla esperienza maturata da un agente possono essere fatte delle assunzioni per il futuro • Sensing: quali variabili d’ambiente considera un agente prima di prendere decisioni sui passi futuri? • Interaction: Come interagiscono gli utenti? (direttamente tra loro, passando per l’ambiente…) • Stochasticity: Ci sono delle entità che variano in maniera casuale nel tempo? • Collectives: Come interagiscono gli agenti nella collettività? • Observation MASON Per questa sezione si possono ricavare delle informazioni in maniera automatica analizzando (dal punto di vista semantico) alcuni metodi (metodo start della classe SimState e metodo step degli agenti). Nota: le informazioni che non saranno generate in maniera automatica, saranno chieste in input all’utente. AutomaticABMsdocumentation - Simone Romano

28. 5)Initialization QUESTION • What is the initial state of the model world, i.e., at time t = 0 of a simulation run? In detail, how many entities of what type are there initially, and what are the exact values of their state variables (or how were they set stochastically)? Is initialization always the same, or is it allowed to vary among simulations? Are the initial values chosen arbitrarily or based on data? MASON Possiamoestrapolare in manieraautomaticainformazioniriguardo lo statoiniziale del modello. Il metodostart dellaSimStateinizializza la simulazione. Automatic ABMs documentation - Simone Romano

29. 6) Input data QUESTION • Does the model use input from external sources such as data files or other models to represent processes that change over time? In modelli che descrivono sistemi reali, alcune informazioni potrebbero variare dinamicamente e quindi dipendere da alcuni input. Automatic ABMs documentation - Simone Romano

30. 7)Submodels • What, in detail, are the submodels that represent the processes listed in ‘Process overview and scheduling’? Nellafase 4 (Processoverview and scheduling) è stata creata una lista di azioni svolte dalle varie entità; qui tali azioni possono essere descritte approfonditamente. Automatic ABMs documentation - Simone Romano

31. Panoramica modelli di simulazione basati sugli agenti - MASON • Doxygen • Può aiutarci? • ODD Protocole MASON • Doxygen e ODD protocol • Semanticanalysis of MASON code • AbstractSyntaxTree Automatic ABMs documentation - Simone Romano

32. Cosa otteniamo con doxygen • Come già anticipato possiamo creare dei moduli e strutturare la documentazione Automatic ABMs documentation - Simone Romano

33. Ricreiamo ODD Automatic ABMs documentation - Simone Romano

34. Sintassi doxygen • Definizione gruppo SimulationModel • Definizione del gruppo Purpose @ingroupSimulationModel • Definizione del gruppo Entities @ingroupSimulationModel • … Automatic ABMs documentation - Simone Romano

35. Cosa richiede questo? • Imparare ad usare doxygen • File di configurazione • Come si commenta il codice • Individuare le parti del codice MASON direttamente collegate al modello (e alle richieste di ODD) e commentarle opportunamente per arrivare al risultato proposto. Automatic ABMs documentation - Simone Romano

36. Panoramica modelli di simulazione basati sugli agenti - MASON • Doxygen • Può aiutarci? • ODD Protocole MASON • Doxygen e ODD protocol • Semanticanalysis of MASON code • AbstractSyntaxTree Automatic ABMs documentation - Simone Romano

37. Semanticanalysis of MASON code • Analizzare sistemi di simulazione scritti utilizzando MASON • Estrarre informazioni semantiche dal codice STRUTTURA RICORRENTE MODELLI MASON Automatic ABMs documentation - Simone Romano

38. Ambiente - SimState • Dimensione della griglia principale (solitamente chiamate height-weight) • Stato iniziale della simulazione partendo dal metodo start • Alcuni coefficienti che (solitamente) modificano le griglie durante la simulazione, rappresentanti quindi alcuni fenomeni • Costante rappresentante il numero di agenti • Variabili relativi alle griglie su cui si svolge la simulazione • Metodostart() che: • Inizializza le griglie • Crea gli agenti e li aggiunge allo schedule Automatic ABMs documentation - Simone Romano

39. Agente - Steppable • Variabile descrivente la locazione attuale dell’utente • Metodo step che (nella maggior parte dei casi) ricava l’oggetto SimState dell’ambiente e svolge delle operazioni Automatic ABMs documentation - Simone Romano

40. Panoramica modelli di simulazione basati sugli agenti - MASON • Doxygen • Può aiutarci? • ODD Protocole MASON • Doxygen e ODD protocol • Semanticanalysis of MASON code • AbstractSyntaxTree Automatic ABMs documentation - Simone Romano

41. AbstractSyntaxTree • The Abstract Syntax Tree is the base framework for many powerful tools of the Eclipse IDE, including refactoring, Quick Fix and Quick Assist. The Abstract Syntax Tree maps plain Java source code in a tree form. This tree is more convenient and reliable to analyse and modify programmatically than text-based source. http://www.eclipse.org/articles/article.php?file=Article-JavaCodeManipulation_AST/index.htmle.  Automatic ABMs documentation - Simone Romano

42. Struttura • Codice java da analizzare • AST • Modifichiamo/analizziamo l’AST • Salviamo le modifiche Automatic ABMs documentation - Simone Romano

43. Esempio 1 • SimStateanalysis - example • Utilizzando AST analizziamo le variabili della classe che estende SimState ODD protocol Entities, state variables and scales Automatic ABMs documentation - Simone Romano

44. Esempio 2 • Metodo step di un oggetto Steppable • Dovrebbe dare diverse informazioni • Come varia la sua posizione • Su quale fieldvà ad agire • … • Tuttavia ci dice veramente poco perché il core del metodo è stato affidato alle funzioni • depositPheromone • act Automatic ABMs documentation - Simone Romano

45. Esempio 2 InvokemethoddepositPheromonethat: InvokemethodgetObjectLocation After invocation of getObjectLocation method: IfAntsForage.ALGORITHM == AntsForage.ALGORITHM_VALUE_ITERATION IfhasFoodItem There is a for loop that while dx < 2 There is a for loop that while dy < 2 … InvokemethodsetObjectLocation After invocation of setObjectLocation method: Ifaf.sites.field[max_x][max_y] == AntsForage.FOOD There is an assignment for reward to value af.reward … Invokemethodactthat: InvokemethodgetObjectLocation After invocation of getObjectLocation method: IfhasFoodItem … AutomaticABMsdocumentation - Simone Romano

46. Sviluppi futuri • Eclipseplugin • Analisi semantica di codice MASON • Auto-generazione commenti • Estrazione documentazione con Doxygen secondo lo standard ODD Automatic ABMs documentation - Simone Romano