introduction to automatic abms documentation keywords: doxygen odd protocol mason documentation...
TRANSCRIPT
Introduction to automatic ABMs documentation
Keywords:• Doxygen
• ODD protocol• MASON documentation
Simone Romano
Automatic ABMs 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 • 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-agenteBranca 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
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 • Può aiutarci?
• ODD Protocol e MASON
• Doxygen e ODD protocol
• Semantic analysis of MASON code
• Abstract Syntax Tree
• 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
Automatic ABMs documentation - Simone Romano
Utilizzo di doxygen
PASSI:1. Creazione file di configurazione2. 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.
OUTPUT:LATEX HTMLPDF
Automatic ABMs documentation - Simone Romano
File di configurazioneCaratteristiche principali
• INPUT• OUTPUT_DIRECTORY• PROJECT_NAME• INLINE_SOURCES• REFERENCED_BY_RELATION
If the REFERENCED_BY_RELATION tag is set to YES then for each documentedfunction all documented functions referencing it will be listed.The default value is: NO.
• REFERENCES_RELATIONIf the REFERENCES_RELATION tag is set to YES then for each documented functionall 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 http://www.graphviz.org/
• HAVE_DOT = YES
• DOT_PATH
• DOT_NUM_THREADS
• CLASS_GRAPH
File di configurazione - grafici
Automatic ABMs documentation - Simone Romano
• CALLER_GRAPH
• CALL_GRAPH
File di configurazione - grafici
Automatic ABMs documentation - Simone Romano
Commenti al codiceDiversi 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 strutturandola documentazione secondo le nostre esigenze.
Automatic ABMs documentation - Simone Romano
Creazione moduli
• Per generare moduli bisogna definirli con la sintassi• @defgroup GroupName Brief Description
• Sarà ora possibile aggiungere elementi del codice al gruppo con la sintassi• @ingroup GroupName
posto sull’entità da documentare
• E’ possibile creare gruppi in altri gruppi:/** * @defgroup Field * @ingroup SimulationModel */
• Tornando al file di configurazione• (*) INLINE_GROUPED_CLASSES include le informazioni
delle classi appartenenti al gruppo all’internodel gruppo stesso.
Automatic ABMs documentation - Simone Romano
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 = YESnel 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• 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, 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
• 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
1. Purpose2. State variables and scales3. Process overview and scheduling4. Design concepts
1. Emergence2. Adaption3. Fitness4. Prediction5. Sensing6. Interaction7. Stochasticity8. Collectives9. Observation
5. Initialization6. Input7. 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)”.
Automatic ABMs documentation - Simone Romano
1)Purpose
QUESTION• What is the purpose of the model?• E’ importante non aggiungere dettagli sul funzionamento del modello a
questo livello di documentazione.
MASONNon possiamo rispondere in maniera automatica a questa domanda.
2)Entities, state variables, and scalesQUESTION• 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
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
2)Entities, state variables, and scales
Automatic ABMs documentation - Simone Romano
MASONPossiamo rispondere (in parte) in maniera automatica.• Agents/individuals
• Steppable
• Spatial units (es. grid cells) 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.
2)Entities, state variables, and scales
Automatic ABMs documentation - Simone Romano
3) Process overview and schedulingQUESTION• Who (i.e., what entity) does what, and in what order?
• Non scendere nei dettagli ma elencare una lista delle azioni svolte dalle entità; ciascuna di queste azioni può essere approfondita nella sezione SUBMODELS
• When are state variables updated?
MASONPossiamo rispondere a queste domande in maniera automatica.• Who (i.e., what entity) does what, and in what order?
• “schedule.scheduleRepeating” dà informazioni su come verranno schedulati gli agenti
• When are state variables updated? • Per ogni agente, il metodo «step» dà informazioni riguardo la sequenza di azioni effettuate dall’agente
ad ogni step.
4)Design concepts1. 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 esperienza5. Prediction: in base alla esperienza maturata da un agente possono essere fatte delle assunzioni per il futuro6. 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
MASONPer 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
Automatic ABMs documentation - Simone Romano
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?
MASONPossiamo estrapolare in maniera automatica informazioni riguardo lo stato iniziale del modello. Il metodo start della SimState inizializza la simulazione.
Automatic ABMs documentation - Simone Romano
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• Semantic analysis of MASON code
• Abstract Syntax Tree
Automatic ABMs documentation - Simone Romano
Cosa otteniamo con doxygen
• Come già anticipato possiamo creare dei moduli e strutturare la documentazione
Automatic ABMs documentation - Simone Romano
Ricreiamo ODD
Automatic ABMs documentation - Simone Romano
Sintassi doxygen
• Definizione gruppo SimulationModel• Definizione del gruppo Purpose @ingroup SimulationModel• Definizione del gruppo Entities @ingroup SimulationModel• …
Automatic ABMs documentation - Simone Romano
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• 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
ELEMENTI SEMANTICA
extends SimState Ambiente
implements Steppable Agente
Automatic ABMs documentation - Simone Romano
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
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.
http://www.eclipse.org/articles/article.php?file=Article-JavaCodeManipulation_AST/index.htmle.
Automatic ABMs documentation - Simone Romano
Struttura
• Codice java da analizzare• AST• Modifichiamo/analizziamo l’AST• Salviamo le modifiche
Automatic ABMs documentation - Simone Romano
Esempio 1SimState analysis - example• Utilizzando AST analizziamo le variabili della classe che estende SimState
ELEMENTI SEMANTICA
IntGrid2D Variable sites represent a field of simulation. It’s initial value is:WIDTH = GRID_WIDTHHEIGHT = GRID_HEIGTHVALUE = 0
GRID_WIDTH Initial value of GRID_WIDTH is 100
GRID_HEIGHT Initial value of GRID_HEIGTH is 100
ODD protocolEntities, state variables and scales
Automatic ABMs documentation - Simone Romano
Esempio 2
• 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 2Invoke method depositPheromone that: Invoke method getObjectLocationAfter 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 setObjectLocationAfter 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 getObjectLocationAfter invocation of getObjectLocation method:If hasFoodItem …
Automatic ABMs documentation - Simone Romano
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