Name:-         	ABMS-Benchmark-FLAME
Authors:-      	Andreu Moreno Vendrell ([email protected], [email protected])
		Anna Sikora ([email protected])
 		Eduardo César ([email protected])
Copyright (c) 2018 Universitat Autònoma de Barcelona, Escola Universitària Salesiana de Sarrià
Date:-         	October 4, 2018

This file is part of the ABMS-Benchmark-FLAME distribution (https://github.com/HPCA4SE-UAB/ABMS-Benchmark-FLAME.git).

Based on: Alban Rousset, Bénédicte Herrmann, Christophe Lang, Laurent Philippe
A survey on parallel and distributed multi-agent systems for high performance comput-
ing simulations Computer Science Review 22 (2016) 27–46

(1) INTRODUCTION
-----------------
Agent-based modeling and simulation (ABMS) is a class of computational models for
simulating the actions and interactions of autonomous agents with the goal of assessing
their effects on a system as a whole. Several frameworks for generating parallel ABMS
applications have been developed taking advantage of their common characteristics,
but there is a lack of a general benchmark for comparing the performance of generated
applications. We propose and design a benchmark that takes into consideration the
most common characteristics of this type of applications and includes parameters for
influencing their relevant performance aspects. We provide an initial implementation of
the benchmark for FLAME one of the most popular parallel ABMS
platforms, and we use it for comparing the applications generated by these platforms.

(2) REQUIRED 
--------------------
- Open MPI 1.10.2
- TAU 2.26.3
- uuid C library (https://sourceforge.net/projects/libuuid/)
- fnv library (http://isthe.com/chongo/src/fnv/fnv-5.0.3.tar.gz)
- fftw3 library (http://www.fftw.org/) 
- FLAME  (xparser and libmboard) (http://flame.ac.uk/)

(3) USAGE (Unix/Linux)
-----------------------------
1. Model parameter selection, 1st. part
	-Size of communication message:
	Select the desired value of COM_BUFFER_SIZE at persons_interact.c source code
	Put the same size to agentCooperate message in persons_interact.xml

	-Max number of agents to play with 
	Select the desired value of MAX_AGENTS_TO_PLAY at persons_interact.c source code
	
	-Size of spaces where agents move around
	Select the desired height and width at gen_file_init.cpp source code

	-Interaction radius between agents
        Select the desired radius at gen_file_init.cpp source code

	-Birth rate center, position where birth_rate applies totally, from this point it goes down lineally until borders of space
	Select the desired center_birth_x and center_birth_y at gen_file_init.cpp source code

	-Death rate center, position where Death_rate applies totally, from this point it goes down lineally until borders of space
        Select the desired center_death_x and center_death_y at gen_file_init.cpp source code

2. Model parameter selection, 2n part, and generation of initial state file
	-Compilation of gen_file_init.cpp:
	g++ gen_file_init.cpp -I/home/caos/amoreno/sfw/include/ -L/home/caos/amoreno/sfw/lib -luuid -lfnv -o gen_file_init

	-Generation of initial state file
	./gen_file_init  num_persons birth_rate death_rate fft_vector_size
 
	num_persons: number of agents
	birth_rate: birth probability, interval [0,1], 0: no birth, 1: 100% probability of birth
	death_rate: death probability, interval [0,1], 0: no death, 1: 100% probability of death
	fft_vector_size: FFT vector size, must be a power of 2	

	For example: ./gen_file_init 1000 0.02 0.02 1024

	returns: 
		0.xml file with agents (for FLAME)
		0.data file with agents (for Repast HPC)
		fft.data file with FFT vector

3. Model preprocessing

	-(Adapt following lines to your environment)
	module load gcc/7.2.0
	module load openmpi/1.10.2
	export PATH=/home/caos/amoreno/sfw/tau-2.26.3/x86_64/bin/:$PATH
	export TAU_MAKEFILE=/home/caos/amoreno/sfw/tau-2.26.3/x86_64/lib/Makefile.tau-mpi-pdt 
	export TAU_COMM_MATRIX=1

	../../sfw/UABFLAME/FLAME/xparser-0.17.0/xparser persons_interact.xml -p

4. Model compilation

	-FLAME xparser generates a Makefile, it needs to be adapted a little bit, we create a new Makefile with configure tool
	autoconf

	-If you want TAU instrumentation tool
	./configure --with-tau --with-libsroot-libdir=/home/caos/amoreno/sfw/
	or if not
	./configure  --with-libsroot-libdir=/home/caos/amoreno/sfw/
	
	-Finally make
	make

5. Model execution

	-Some scripts samples are provided in slurm_script_samples directory for SLURM 
	sbatch ModelFLAME_slurm_de1000a10000pas2000.sh 

6. Getting results

	-A script to extract performance results from TAU output file is provided.
	./Get_results

	-To get agents distribution
	./PreprocessAgentsDistribution 12 EnodeX-100-1.xml.tgz
	Rscript GenerationAgentsDistribution.R	

(4) LICENSE (GPL):
-------------
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.