Name:-         	ABMS-Benchmark-FLAME
Authors:-      	Juanjo Rodriguez Guerra (jrodriguezgue@uoc.edu, juanjose.rodriguezg@uab.cat)
                Josep Jorba Esteve (jjorbae at uoc.edu)
Copyright (c) 2018 Universitat Oberta de Catalunya, Universitat Autònoma de Barcelona
Date:-         	October 21, 2018

This file is part of the ABMS-Benchmark-FLAMEGPU distribution (https://github.com/HPCA4SE-UAB/ABMS-Benchmark-FLAMEGPU.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 
--------------------
- CUDA 8.0 (https://developer.nvidia.com/cuda-80-ga2-download-archive)
- cudpp 2.2 library (http://cudpp.github.io/releases/2014/08/31/cudpp-2-2-released.html)
- glew 2.1.0 library (https://sourceforge.net/projects/glew/files/glew/2.1.0/)
- cuFFT library (https://docs.nvidia.com/cuda/cufft/index.html) 
- Apache Xalan XSLT preprocessor (http://xalan.apache.org/index.html, http://apache.rediris.es/xalan/xalan-j/binaries/)
- FLAMEGPU  (http://www.flamegpu.com/, https://github.com/FLAMEGPU/FLAMEGPU/releases/tag/v1.4.3)

(3) USAGE (Unix/Linux)
-----------------------------
1. Model parameter selection
	-Size of communication message:
	As FlameGPU doesn't support arrays for messages variables, there is a different persons_interact.c
        source file for each model which have a folder each:
              * ModelNP64:   Non partitioned messaging with 64B load
              * ModelNPno64: Non partitioned messaging without 64B load
              * ModelP64:    Partitioned messaging with 64B load
              * ModelPno64:  Partitioned messaging without 64B load

	-Size of FFT vector:
        As CUDA works with FFT through cuFFT library we have had to modify the simulation.cu file
        generated by framework templates. FFT calculation has been embedded into person_compute
        fuction replacing the GPUFLAME_compute kernel. That's way we have a simulation.cu file 
        inside the folder of each model. The value is defined by N variable.

	-Size of spaces where agents move around
	Defined in each init data file, and into persons_interact.c source code

	-Interaction radius between agents
        Defined in each init data file, and into persons_interact.c 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

	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	

	For example: ./gen_file_init 1000 0.02 0.02

	returns: 0.xml file

3. Model preprocessing

        - At folder create_exec_results_scripts we have the createModel.sh script which has 
        the commands to generate the model. It is necessary to adapt this script to your
        environment. 

4. Model compilation

	- At the makefile_samples folder there is a Makefile file which is necessary to generate 
        the model. It will be necessary to adapt this file to your environment and after execute:
	make

5. Model execution

	- At folder create_exec_results_scripts folder there is exec_get_results.sh script, which
        launch and get the time execution model. It will be necessary to adapt the file to your
        environment and, if it is the case, modify the line with:
        ./model $directoryname/0.xml 100 $gpu 

        This line launch the model file "./model", with the init file "$directoryname/0.xml",
        executing 100 iteration, at the GPU device "$gpu"

6. Getting results

	- At the main.cu source file generated by model templates there is a OUTPUT_TO_XML global
        variable which we can change to 1 if we want XML output files as a result. Moreover, the 
        execution script mentioned at before point always provides the model execution time.

(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/>.