ETACE Virtual Appliance
User Manual
Gregor B¨ohl, Sander van der Hoog, Bielefeld University
Chair for Economic Theory and Computational Economics (ETACE)
April 18, 2014
Contents
1
2
3
4
5
Purpose . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . .
Programmes, Documentation and
Quick Starter Guide . . . . . . .
Flame Modeling Environment . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
the Eurace@Unibi Model
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
1
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2
2
2
3
4
1 Purpose
1
2
Purpose
This User Manual for the ETACE Virtual Appliance describes the programmes available and
the general workflow with the Flexible Large-scale Agent-based Modelling Environment (Flame,
http://www.flame.ac.uk/) and its respective tools, with the focus on economic analyses using the
Eurace@Unibi model.
2
Overview
The intention behind this software collection is to make every step related to the initialization,
execution and analysis of the Eurace@Unibi agent-based simulation model as easy as possible.
Hence it addresses the issue of reproducibility of simulations-based research (Stodden, 2010).
Settings
Note that for maximum portability, the use of system resources is set to a minimum. You can
change these settings:
• Enable hardware virtualization support in your own system’s BIOS to run in multicore mode (normally under menu ”CPU” in BIOS).
• In the settings of the virtual machine itself (i.e. in the client f.i Oracle’s VirtualBox, not
in this Virtual Appliance), you can change the number of assigned CPU cores and RAM
memory.
3
Programmes, Documentation and the Eurace@Unibi Model
This software package is based on the SliTaz distribution of free software, that includes the
Linux kernel. The corresponding documentation can also be found in aforementioned folder.
The programs provided in the Virtual Appliance (including their dependencies) are:
XParser
XParser GUI
Flame Editor & Agent GUI
Population GUI
Simulation GUI
:
:
:
:
:
Parser for the model XML file.
Wrapper for XParser to parse the model XML and compile using gcc.
Generates the model.xml file, the XML description of your model.
Generates initialization files and population settings (0.xml and 0.pop).
Settings for simulation experiments and data analysis.
Apart from the GNU C Compiler, all relevant documentation for the programmes can be
found in the Documentation folder on the Desktop.
Eurace@Unibi Source Code
The following versions of the Eurace@Unibi model are included and can be found in the
Models folder on the Desktop:
Dawid
Dawid
Dawid
Dawid
et al., 2011
and Gemkow, 2013
et al., 2013a
et al., 2013b
:
:
:
:
full source code of Eurace@Unibi 1.0
main, model.xml, 0.pop & 0.xml for replication
main, model.xml & 0.xml for replication
main, model.xml & 0.xml for replication
4 Quick Starter Guide
4
3
Quick Starter Guide
To get root access in a terminal, type su with password root. The Super User is likewise root
with password root. All the relevant files have been placed on the Desktop
(/home/eurace/Desktop), whereas additional libraries (Libmboard, R, Python, GSL) have been
installed directly into the system.
If you just want to run the Eurace@Unibi model, use the Simulation GUI to run simulations
and to create plots.
1. Settings:
• When prompted, select an experiment folder in which the plots and experiment
data will be stored.
• In Settings → Set Paths: Set paths to: model.xml, 0.xml, R scripts.
• The model.xml is the file in which the model structure is defined.
• The executable is called main, located in the same folder as the model.xml file.
• The initial data file, the 0.xml, is located in the subfolder ”experiment”/its.
• The path to the R scripts should already be pre-configured as:
/home/eurace/Desktop/src/JavaGUI/src/Data Analysis GUI Serial.
2. Setup experiment:
• Choose the number of iterations: 6000 by default (which roughly corresponds to 25
years). NOTE: In the Simulation GUI you always have to confirm when changing a
setting by pressing Enter!
• Set the number of batch runs (repetitions, using different random seeds).
• Choose the Agents you would like to store data of, by clicking Record: Period is the
periodicity at which data is stored, Phase is the phase shift.
• The data that is retrieved for the plots can be used for single and batch runs as well
as for parameter analysis. For further explanations see the Simulation GUI Manual.
• If you would like to generate some time series, define the time series in the menu
item Data Analysis. Define Time Series: select variables to extract from the
database, then choose Normal Time Series to specify what plotting method to use.
• Once you are done click Build Experiment. In the respective Terminal you will be
informed when process of building the experiment is done. This should not take
more than a couple of seconds.
• Then click Run Experiment. Depending on the number of batch runs, iterations and
your choice of plots this might take quite some time (benchmark is 15 minutes for
one run of 6000 iterations).
3. Output:
The plots are stored in the /Plots subfolder of your experiment folder (by default:
/home/eurace/Desktop/exper). We can select and plot any memory variable that was
selected for retrieval from the database in Step 1, using various plotting features that are
explained in detail in the manual for the Simulation GUI.
5 Flame Modeling Environment
5
4
Flame Modeling Environment
The Eurace@Unibi model is implemented in the Flame development framework. We provide
the full source code for the Eurace@Unibi v1.0 model. If you want to get a deeper
understanding of this code, make changes (i.e. implement a new policy rule), experiment with
different initial populations or even create a completely new model from scratch, continue
reading.
What is Flame?
In a nutshell:
- Flame is a program generator. It generates a simulation executable from C and XML files.
- Flame is a domain-specific language programmed in C, that provides facilities (see Flame
user manual) for higher-level programming of economic and biological models.
- It uses the markup language XMML (X-Machine Modeling Language) for the declaration of
functions and variables, and uses C templates to generate the final C code of the
simulator.
- All model functions are written in plain C code (a small subset of C), while the scheduling of
agents, functions and messages is coded in XML with easy-to-use GUIs.
- The model.xml file is parsed by the Xparser, producing C code for the simulator. This C
code is then compiled together with the user-provided C code for the agent functions,
which generates the simulation executable.
- Libmboard (the Message Board Library) provides facilities for message passing using MPI.
- Flame can generate both serial or parallel C code for multi-core computing.
Flame Model Development Cycle
A Flame model development cycle goes through several stages, as illustrated in Fig.1. A
detailed workflow is given below. For editing or producing new models quickly, we note that:
• To view a model and its agents, functions, messages, etc., use the Flame Editor or Agent
GUI and open the model.xml file.
• To generate initial data (0.xml file), use the Population GUI. Also use this to view or edit
a pre-existing .pop file (population description file). These files can be found in the same
/its folder as the default 0.xml file.
• In order to keep the image of this virtual application lightweight we do not provide a
front-end for C programming. To view and edit the code, you may use leafpad, vi or
nano, all available from the terminal. If required, additional programmes can be installed
by using the SliTaz package manager tazpkg. For further details, we refer to the SliTaz
documentation.
• Once you have created a new model.xml or 0.xml file, use the Xparser GUI to parse and
compile the model. After double- clicking the desktop shortcut, choose the model.xml file
5 Flame Modeling Environment
5
(for the Eurace@Unibi called eurace model.xml). After x-parsing the model you will be
prompted to press ENTER to compile the model.1
Step 1: Flame Editor & Agent GUI – Model Design
The model design stage starts with setting up the general model hierarchy. The entire model
can be subdivided into several modules, each having an internal structure that adheres to the
XML definition. Each module will contain a well-defined description of the agents as
X-Machines.2
In the next step we define the agent types, their memory variables, functions, and the
activation structure of the functions (scheduling of functions can be either time- or event-based,
or both). For time-based scheduling, you can define time units in the model environment. At
this step we also define message definitions, and set the input and output messages for the
functions. In addition, the environment constants (fixed model parameters) can be defined.
Step 2: Xparser GUI – Parsing and Compiling
Use the Xparser GUI to parse the model.xml file and compile the C code.
Parsing and compiling from the command-line:
• Typing xparser will produce:
xparser (Version 0.17.1)
Usage: xparser [XMML file] [-s | -p] [-f]
-s
Serial mode (default)
-p
Parallel mode
-f
Final production mode
The serial mode produces C code for standard compilation with GCC. The resulting
executable is for single-core processing. The parallel mode produces C code for compiling
using an MPI-compatible compiler (such as mpich). The resulting executable is for
multi-core processing, and requires you to install an MPI software interface on your
target system.
In production, or final, mode, the xparser produces production code of the model. This
code is smaller in size, and should execute faster. On the other hand, it has fewer checks,
so use this mode with care. In particular, the production mode should only be used after
you have fully debugged your code.
• To parse your model in debug, serial mode, use:
$ xparser model.xml
1
For advanced users: the GUI version of the xparser does not provide any additional options. If you require
these, you will have to run the xparser from the command line: /home/eurace/Desktop/Models/xparser-0.17.1/
xparser. Options include: -p: parallel code, -f: final production mode (random seeds are initialized on system
time).
2
The XMML of Flame has been defined as a hierarchical Document Type Definition. This means that Flame
accepts a nested model definition consisting of sub-models, which again may consist of sub-sub-models, and so on
and so forth. This is possible due to the fact that a collection of Communicating Stream X-Machines can again
be considered an CSX-Machine.
5 Flame Modeling Environment
Fig. 1: Overview of the Flame Workflow and Programmes in the ETACE Virtual Appliance.
6
5 Flame Modeling Environment
7
• To parse your model in production mode, use:
$ xparser -f model.xml
• To produce parallel code, use:
$ xparser -p model.xml
• Next, compile the C code:
$ make clean all (or make)
Using the GSL Library for random number generation
Random numbers are very important for scientific computing and the random number
generators provided by the native operating system may be considered inadequate.3 To
remedy this, FLAME provides a mechanism for calling the random number generators of the
GNU Scientific Library (GSL)4 , provided that they have been installed on the target system.
Xparser v0.17.1
The seed of the random number sequence is defined as a model parameter GSL RNG SEED
(large caps) of type float in the henvironmenti section of the model.xml file, like so:
<environment>
<constants>
<variable>
<type>float</type>
<name>GSL_RNG_SEED</name>
<description>Random seed for the GSL Random Number Generator</description>
</variable>
</constants>
</environment>
Using this, the xparser will generate additional code to call the GSL Random Number
Generator. In the current version of FLAME, the mt19937 type of generator is being used.
The value of the random number seed will now have to be set through the hGSL RNG SEEDi
tag in the initial data file (0.xml). If this variable is not provided, it is automatically initialized
on the current system time.5
Alternatively, the generator type and the initial random seed can also be set using the system
environment variables GSL RNG TYPE and GSL RNG SEED (ie., in Linux this would be Bash
environment variables). The random seed provided by the initial data files (0.xml) will
over-ride those given in the system environment variables (Bash).
3
For standard C libraries, it is well-known that the default RNGs such as rand() are inadequate in producing
sufficiently arbitrary random numbers.
4
The GNU Scientific Library is available from: https://www.gnu.org/software/gsl/
5
Careful!: When multiple runs are launched simultaneously at exactly the same time, these will all have the
same random seed. Therefore it is advisable to put a sleep command inbetween the launching of multiple runs.
5 Flame Modeling Environment
8
A note on random seeds and the reproducibility of results
By implementing the random seed as a model parameter in the model.xml file, this mechanism
allows us to use it as input to the simulation. Hence, it is possible to use a different random
seed for each run, while still maintaining full reproducibility. Since the value of the random
seed is stored in the initialization file of each run, we can always reproduce the exact same
random number sequence at a later moment in time.
Alternatively, the user can opt for a ”quasi-random” random number seed. This is achieved by
using the xparser in production, or final, mode:
$ xparser -f model.xml
In production mode, the random seed is initialized based on the system clock. This will
generate a ”randomly drawn” random seed each time the simulation executable is called. This
implies, however, that for each run, a new randomly drawn random seed will be set at the
moment the simulation process is launched. Consequently, there will be no reproducibility of
results since the value of the random seeds will not be stored in any of the 0.xml files.
Stategraph
After Xparsing the model, the model design stage ends and the hierarchical structure can be
inspected through a birds-eye view of the model in a stategraph, an example of which is given
in Figure 2. Such a stategraph shows for every agent its states and the transition functions
between the states. It also shows the branching of agent activities, depending on time
conditions (monthly or yearly activation, for example) or on event-based conditions (a memory
variable of an agent). In addition, the stategraph also shows the flow of information between
the agents, by messages.
Step 3.1: Population GUI – Agent Population Design
After the entire model design stage is done, the next stage is to initialize our agent population.
This initialization is done using the PopGUI, which uses the Python language. This stage
consists of setting the size of the agent population, the number of regions, and the
subpopulation of agents in each region. We can initialize all model constants and agent
memory variables. For each agent memory variable we can define relationships on the
initialization values of other memory variables of the same agent or of other agents, or on the
values of model constants. It is possible to validate the complete set of relationships before
instantiating the population. At the end of this stage, a complete population description file
(called 0.pop) has been generated, with all the interdependencies between the agents’ initial
values resolved. From this, the input file (0.xml) is generated.
Step 3.2: Simulation GUI – Design of the Computational Experiment
The experiment design stage consists of:
1. Settings of the parameter variations
2. Settings for data storage options: which agents to store, at what frequency (every
iteration, every month,...)
3. Running a set of batch runs
4. Launching the simulation
5 Flame Modeling Environment
9
Step 4: Simulation GUI – Visualization and Analysis of the Data
After the simulation has finished and all data has been produced, the final stage is the data
analysis stage. For this, we again make use of the Simulation GUI.
Pre-requisites for this step:
simulation runs.
A set of SQL databases is available, containing all data from
Step 1. Selection of Memory Variables
In the Simulation GUI it is possible to load a model.xml file, in two ways:
1. The complete model.xml file: use this option to load all agent memory variables.
This setting allows to plot any memory variable that was stored during the
simulation.
2. A subset shadow model.xml file: use this option to load only a subset of agent
memory variables. This setting allows to plot only those memory variables that are
mentioned in the subset file.
The usefulness of the subset file becomes apparent when dealing with a large model in
which agents have up to 100 memory variables. Instead of retrieving all memory
variables, only those that are mentioned in the shadow model.xml file will be available for
plotting.
Note 1: the SQL databases always contain the complete set of data.
Note 2: In both settings, it will be possible to use any parameter for parameter
sensitivity analysis. The information which parameters are available comes from a
separate environment.xml file.
Step 2. Plotting of Retrieved Data
Next, we can select and plot any memory variable that was selected for retrieval from the
database in Step 1, using various plotting features, such as Time series, Box-Whiskers
plots, Histograms (population density distribution plots) and Scatter plots (delay plots,
or phase plots).6
The plots are automatically saved as PDF files (or optionally as PNG or EPS) in the folder
selected in the settings.
In case you want to use Flame to develop a new model, a tutorial and further materials are
found in the Documentation folder.
6
The Simulation GUI provides a variety of further plotting options, such as correlation coefficients, bandpass
filtered time series, Beveridge curves, Philipps curves. For further information we recommend the Simulation GUI
manual.
5 Flame Modeling Environment
layer 0
01
10
fox_start_state
rabbit_start_state
Fox_send_location
Rabbit_send_location
01
fox_location
rabbit_location rabbit_location
01
layer 1
layer 2
GlobalAgent_count_agents
Fox_chase_all_rabbits
GlobalAgent_end_state
02
fox_location
rabbit_eaten
Fox_starvation
Rabbit_dodge_foxes
fox_end_state
rabbit_end_state
Fig. 2: State graph of a simple predator-prey model with foxes and rabbits. Boxes are transition
functions, circles and elipses are states, and green lines are messages.
REFERENCES
11
References
Dawid, H. and Gemkow, S. (2013). How do social networks contribute to wage inequality?
insights from an agent-based analysis. Industrial and Corporate Change.
Dawid, H., Gemkow, S., Harting, P., van der Hoog, S., and Neugart, M. (2011). The
Eurace@Unibi model: An agent-based macroeconomic model for economic policy analysis.
Bielefeld Working Papers in Economics and Management.
Dawid, H., Harting, P., and Neugart, M. (2013a). Cohesion policy and inequality dynamics:
Insights from a heterogeneous agents macroeconomic model. Available at SSRN 2369187.
Dawid, H., Harting, P., and Neugart, M. (2013b). Spatial labor market frictions and economic
convergence: policy implications from a heterogeneous agent model. Bielefeld Working
Papers in Economics and Management.
Stodden, V. C. (2010). Reproducible research: Addressing the need for data and code sharing
in computational science. Computing in Science & Engineering, 12(5):8–12.