Introduction to automatic ABMs documentation Keywords: Doxygen ODD protocol MASON documentation Simone Romano

Cosa vedremo: Panoramica modelli di simulazione basati sugli agenti - MASON Doxygen Può aiutarci? ODD Protocol e MASON Doxygen e ODD protocol Semantic analysis of MASON code Abstract Syntax Tree Automatic ABMs documentation - Simone Romano

Panoramica modelli di simulazione basati sugli agenti - MASON Panoramica modelli di simulazione basati sugli agenti - MASON Doxygen Può aiutarci? ODD Protocol e MASON Doxygen e ODD protocol Semantic analysis of MASON code Abstract Syntax Tree Automatic ABMs documentation - Simone Romano

Sistemi multi-agente Automatic ABMs documentation - Simone Romano 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

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

Panoramica modelli di simulazione basati sugli agenti - MASON Doxygen Doxygen Può aiutarci? Può aiutarci? ODD Protocol e MASON Doxygen e ODD protocol Semantic analysis of MASON code Abstract Syntax Tree Automatic ABMs documentation - Simone Romano

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D. Multipiattaforma Linux - MAC OS - Windows Configurabile File di configurazione Automatic ABMs documentation - Simone Romano

Utilizzo di doxygen PASSI: 1.Creazione file di configurazione 2.Esecuzione di doxygen CREAZIONE FILE DI CONFIGURAZIONE Tramite shell lanciando il comando doxygen –g Tramite applicazione dedicata Plug-in per eclipse, ECLOX ESECUZIONE doxygen pathFileConfig 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. Automatic ABMs documentation - Simone Romano OUTPUT: LATEX HTML PDF

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 function all 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

Necessità di Graphviz HAVE_DOT = YES DOT_PATH DOT_NUM_THREADS CLASS_GRAPH Automatic ABMs documentation - Simone Romano File di configurazione - grafici

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

Commenti al codice Diversi stili Javadoc Style: /** * Comment here */ Possiamo commentare Package Classi Metodi Parametri Parametri di metodi Void foo(int v /**<[in] does comment for v.*/) Immagini \image html pathImg Automatic ABMs documentation - Simone Romano

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

Creazione moduli Per generare moduli bisogna definirli con la GroupName Brief Description Sarà ora possibile aggiungere elementi del codice al gruppo con la GroupName posto sull’entità da documentare E’ possibile creare gruppi in altri gruppi: /** Field SimulationModel */ 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

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

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 Qual è il problema? Automatic ABMs documentation - Simone Romano

Panoramica modelli di simulazione basati sugli agenti - MASON Doxygen Può aiutarci? ODD Protocol e MASON ODD Protocol e MASON Doxygen e ODD protocol Semantic analysis of MASON code Abstract Syntax Tree Automatic ABMs documentation - Simone Romano

ODD Protocol (Overview, Design concepts and Details) Come documentare un ABMs (agent-based models) Pubblicato nel 2006 per standardizzare le descrizioni di ABMs (modelli basati sugli agenti). Volker Grimm - Helmholtz Centre for Environmental Research-UFZ, Department of Ecological Modelling, Permoserstr. 15, Leipzig, Germany Uta Berger - Institute of Forest Growth and Computer Science, Dresden University of Technology, P.O. 1117, Tharandt, Germany Donald L. DeAngelis - USGS/Biological Resources Division and Dept. of Biology, University of Miami, PO Box , Coral Gables, FL 33124, USA J. Gary Polhill - Macaulay Land Use Research Institute, Craigiebuckler, Aberdeen, AB15 8QH, United Kingdom Jarl Giske - 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

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 checklist con le caratteristiche principali da descrivere in un modello. Automatic ABMs documentation - Simone Romano

Elementi del protocollo ODD Automatic ABMs documentation - Simone Romano 1.Purpose 2.State variables and scales 3.Process overview and scheduling 4.Design concepts 1.Emergence 2.Adaption 3.Fitness 4.Prediction 5.Sensing 6.Interaction 7.Stochasticity 8.Collectives 9.Observation 5.Initialization 6.Input 7.Submodels Quando il protocollo ODD viene usato per documentare un ABMs, questo và scritto espicitamente nella documentazione: “the model description follows the ODD (Overview, Design concepts, Details) protocol (Grimm et al., 2006, this work)”.

1)Purpose Automatic ABMs documentation - Simone Romano

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 Automatic ABMs documentation - Simone Romano

Agents/individuals Spatial units (es. grid cells) 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 2)Entities, state variables, and scales

Automatic ABMs documentation - Simone Romano 2)Entities, state variables, and scales

3) Process overview and scheduling Automatic ABMs documentation - Simone Romano

4)Design concepts 1.Basic Principles: in questa sezione vanno inseriti i concetti di base che regolano la simulazione, le ipotesi, l’evoluzione della complessità. 2.Emergence: quali sono le chiavi emergenti del modello? 3.Adaption: in che maniera gli agenti prendono decisioni? 4.Learning: alcuni agenti cambiano il loro comportamento nel tempo in base alla loro esperienza 5.Prediction: in base alla esperienza maturata da un agente possono essere fatte delle assunzioni per il futuro 6.Sensing: quali variabili d’ambiente considera un agente prima di prendere decisioni sui passi futuri? 7.Interaction: Come interagiscono gli utenti? (direttamente tra loro, passando per l’ambiente…) 8.Stochasticity: Ci sono delle entità che variano in maniera casuale nel tempo? 9.Collectives: Come interagiscono gli agenti nella collettività? 10.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. Automatic ABMs documentation - Simone Romano

5)Initialization

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

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

Panoramica modelli di simulazione basati sugli agenti - MASON Doxygen Può aiutarci? ODD Protocol e MASON Doxygen e ODD protocol Doxygen e ODD protocol Semantic analysis of MASON code Abstract Syntax Tree Automatic ABMs documentation - Simone Romano

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

Ricreiamo ODD Automatic ABMs documentation - Simone Romano

Sintassi doxygen Automatic ABMs documentation - Simone Romano Definizione gruppo SimulationModel Definizione del gruppo SimulationModel Definizione del gruppo SimulationModel …

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

Panoramica modelli di simulazione basati sugli agenti - MASON Doxygen Può aiutarci? ODD Protocol e MASON Doxygen e ODD protocol Semantic analysis of MASON code Semantic analysis of MASON code Abstract Syntax Tree Automatic ABMs documentation - Simone Romano

Semantic analysis of MASON code Analizzare sistemi di simulazione scritti utilizzando MASON Estrarre informazioni semantiche dal codice STRUTTURA RICORRENTE MODELLI MASON Automatic ABMs documentation - Simone Romano ELEMENTISEMANTICA extends SimStateAmbiente implements SteppableAgente

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 Metodo start() che: Inizializza le griglie Crea gli agenti e li aggiunge allo schedule Automatic ABMs documentation - Simone Romano

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

Panoramica modelli di simulazione basati sugli agenti - MASON Doxygen Può aiutarci? ODD Protocol e MASON Doxygen e ODD protocol Semantic analysis of MASON code Abstract Syntax Tree Abstract Syntax Tree Automatic ABMs documentation - Simone Romano

Abstract Syntax Tree 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. Automatic ABMs documentation - Simone Romano

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

Esempio 1 Automatic ABMs documentation - Simone Romano SimState analysis - example Utilizzando AST analizziamo le variabili della classe che estende SimState ELEMENTISEMANTICA IntGrid2DVariable sites represent a field of simulation. It’s initial value is: WIDTH = GRID_WIDTH HEIGHT = GRID_HEIGTH VALUE = 0 GRID_WIDTHInitial value of GRID_WIDTH is 100 GRID_HEIGHTInitial value of GRID_HEIGTH is 100 ODD protocol Entities, state variables and scales

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

Esempio 2 Invoke method depositPheromone that Invoke method depositPheromone that: Invoke method getObjectLocation After invocation of getObjectLocation method: If AntsForage.ALGORITHM == AntsForage.ALGORITHM_VALUE_ITERATION If hasFoodItem There is a for loop that while dx < 2 There is a for loop that while dy < 2 … Invoke method setObjectLocation After invocation of setObjectLocation method: If af.sites.field[max_x][max_y] == AntsForage.FOOD There is an assignment for reward to value af.reward … Invoke method act that: Invoke method getObjectLocation After invocation of getObjectLocation method: If hasFoodItem … Automatic ABMs documentation - Simone Romano

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