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
• 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
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
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
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.
2.
Creazione file di configurazione
Esecuzione di doxygen
OUTPUT:
LATEX
HTML
PDF
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
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
File di configurazione - grafici
Necessità di Graphviz
http://www.graphviz.org/
• HAVE_DOT = YES
• DOT_PATH
• DOT_NUM_THREADS
• CLASS_GRAPH
Automatic ABMs documentation - Simone Romano
File di configurazione - grafici
• CALLER_GRAPH
• CALL_GRAPH
Automatic ABMs documentation - Simone Romano
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 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’interno
del 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 = 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
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
• 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.
2.
3.
4.
Purpose
State variables and scales
Process overview and scheduling
Design concepts
1.
2.
3.
4.
5.
6.
7.
8.
9.
5.
6.
7.
Emergence
Adaption
Fitness
Prediction
Sensing
Interaction
Stochasticity
Collectives
Observation
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)”.
Initialization
Input
Submodels
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.
MASON
rispondere in maniera automatica a questa domanda.
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
2)Entities, state variables, and scales
• 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
MASON
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…
• 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
3) Process overview and scheduling
QUESTION
• 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?
MASON
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.
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
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
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 heightweight)
• 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 1
SimState 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_WIDTH
HEIGHT = GRID_HEIGTH
VALUE = 0
GRID_WIDTH
Initial value of GRID_WIDTH
is 100
GRID_HEIGHT
Initial value of GRID_HEIGTH
is 100
Automatic ABMs documentation - Simone Romano
ODD protocol
Entities, 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
Automatic ABMs documentation - Simone Romano
Esempio 2
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