Name:-         	ABMS-Benchmark-Repast
Authors:-      	Andreu Moreno Vendrell (amoreno@euss.cat, andreu.moreno@uab.cat)
		Anna Sikora (anna.sikora@uab.cat)
 		Eduardo César (eduardo.cesar@uab.cat)
Copyright (c) 2018 Universitat Autònoma de Barcelona, Escola Universitària Salesiana de Sarrià
Date:-         	October 4, 2018

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 RepastHPC 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
- fftw3 library (http://www.fftw.org/) 
- Repast HPC 2.3.0  (https://repast.github.io/repast_hpc.html)

(3) USAGE (Unix/Linux)
-----------------------------
1. Model parameter selection, 1t part
	-Size of communication message:
	Select the desired value of COM_BUFFER_SIZE at RepastHPC/include/Agent.h

	-Size of space where agents move arround
	Select the desired HEIGHT and WIDTH at RepastHPC/include/Model.h

	-Interaction radius between agents
        Select the desired radius at RepastHPC/include/Agent.h

	-Max number of agents to play with
	Select the desired value at RepastHPC/include/Agent.h

	-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 RepastHPC/include/Agent.h

	-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 RepastHPC/include/Agent.h

	-birth_rate: birth probability, interval [0,1], 0: no birth, 1: 100% probability of birth
	Select the desired value at RepastHPC/include/Agent.h

	-death_rate: death probability, interval [0,1], 0: no death, 1: 100% probability of death
        Select the desired value at RepastHPC/include/Agent.h
	

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

        -Generation of initial state file (we use the same generation application for Repast and FLAME, we must give birth_rate and death_rate parameters even are not used in Repast)
        ./bin/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: ./bin/gen_file_init 1000 0.02 0.02 1024

        returns: 
		0.xml file with agents (for FLAME, Discard 0.xml file, it is used in the FLAME framework)
		0.data file with agents (for Repast HPC, we use the 0.data as agent initial position file)
		fft.data file with FFT vector



3. Model compilation

	-Go to work directory
	cd work

	-(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 LD_LIBRARY_PATH=/home/caos/amoreno/sfw/lib/:/home/caos/amoreno/sfw/Boost/Boost_1.61/lib/:$LD_LIBRARY_PATH
	export TAU_MAKEFILE=/home/caos/amoreno/sfw/tau-2.26.3/x86_64/lib/Makefile.tau-mpi-pdt 
	export TAU_COMM_MATRIX=1

	-run ./configure with your paths

	Example with TAU:
	./configure --with-tau --with-repast=/home/caos/amoreno/sfw --with-boost-libdir=/home/caos/amoreno/sfw/Boost/Boost_1.61/lib  --with-boost-incdir=/home/caos/amoreno/sfw/Boost/Boost_1.61/include --with-fftw3-incdir=/home/caos/amoreno/sfw/include --with-fftw3-libdir=/home/caos/amoreno/sfw/lib --with-openmpi-libdir=/soft/openmpi-1.10.2/lib

	Example without TAU:
	./configure --with-repast=/home/caos/amoreno/sfw --with-boost-libdir=/home/caos/amoreno/sfw/Boost/Boost_1.61/lib  --with-boost-incdir=/home/caos/amoreno/sfw/Boost/Boost_1.61/include --with-fftw3-incdir=/home/caos/amoreno/sfw/include --with-fftw3-libdir=/home/caos/amoreno/sfw/lib --with-openmpi-libdir=/soft/openmpi-1.10.2/lib

	-run make to compile

	-Set uumber of agents, processors, end time, agents position file and FFT vector file after compilation
	Modify work/props/model.props.

	-Copy 0.data and fft.data to props directory

4. Model execution

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

5. Getting results

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

        -To get agents distribution
        ./PreprocessAgentsDistribution output/sortida1.txt 
        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/>.