introduction to automatic abms documentation keywords: doxygen odd protocol mason documentation...

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


• 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


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


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


• Panoramica modelli di simulazione basati sugli agenti - MASON

• Doxygen • Può aiutarci?





• 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



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


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 (*)


Necessità di Graphviz http://www.graphviz.org/

• HAVE_DOT = YES

• DOT_PATH

• DOT_NUM_THREADS

• CLASS_GRAPH

File di configurazione - grafici

http://www.graphviz.org/




• CALLER_GRAPH

• CALL_GRAPH

File di configurazione - grafici


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


Moduli

• Possiamo creare dei moduli (pagine dedicate nella documentazione)

• Utilità?Raggruppare informazioni semanticamente collegate strutturandola documentazione secondo le nostre esigenze.


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.


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.


• 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?




• ODD Protocol e MASON• Doxygen e ODD protocol




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


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.


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)”.


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



• 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


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

Simone

E' quello che viene spesso fatto dai modellatori di sistemi.


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.



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.


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.


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.





• Doxygen e ODD protocol• Semantic analysis of MASON code



Cosa otteniamo con doxygen

• Come già anticipato possiamo creare dei moduli e strutturare la documentazione


Ricreiamo ODD


Sintassi doxygen

• Definizione gruppo SimulationModel• Definizione del gruppo Purpose @ingroup SimulationModel• Definizione del gruppo Entities @ingroup 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.






• Semantic analysis of MASON code• Abstract Syntax Tree


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


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


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


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.


Struttura

• Codice java da analizzare• AST• Modifichiamo/analizziamo l’AST• Salviamo le modifiche


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


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 …



Sviluppi futuri

• Eclipse plugin• Analisi semantica di codice MASON• Auto-generazione commenti • Estrazione documentazione con Doxygen secondo lo standard ODD

introduction to automatic abms documentation keywords: doxygen odd protocol mason documentation...

Documents

mason mason

doxygen passi

configurazione grafici

java che utilizzano

latex html pdf slide

relation tag

documented entities

documented functions