Name:-         	ABMS-Benchmark-DMASON
Authors:-    
		Cristina Peralta Quesada ([email protected])
		Andreu Moreno Vendrell ([email protected], [email protected])
		Anna Sikora ([email protected])
 		Eduardo César ([email protected])
		Josep Jorba Esteve (jjorbae at uoc.edu, josep.jorba at uab.cat)

Copyright (c) 2020 Universitat Autònoma de Barcelona, Escola Universitària Salesiana de Sarrià, Universitat Oberta de Catalunya
Date:-         	March 4, 2020

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

(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 DMASON one of the popular parallel ABMS
platforms, and we use it for comparing the applications generated by these platforms.

(2) REQUIRED 
--------------------
- DMASON 3.2 (https://github.com/isislab-unisa/dmason)
- JTransforms (https ://sites.google.com/site/piotrwendykier/software/jtransforms)
- uuid C library (https://sourceforge.net/projects/libuuid/)
- fnv library (http://isthe.com/chongo/src/fnv/fnv-5.0.3.tar.gz)

(3) USAGE (Unix/Linux)
-----------------------------
1. DMASON installation
	-Download DMASON 3.2 from https://github.com/isislab-unisa/dmason/archive/master.zip
	-Unzip DMASON on a folder 
		unzip dmason-master dmason-master.zip
	-Add JTransforms [11] java library to DMASON’s pom.xml
	....
	<repository>
		<id>org.jtransforms</id>
		<url>https://github.com/wendykierp/JTransforms/tree/master/src</url>
	</repository>
	...
	<dependency>
		<groupId>com.github.wendykierp</groupId>
		<artifactId>JTransforms</artifactId>
		<version>3.1</version>
		<classifier>with-dependencies</classifier>
	</dependency>
	...
	-NOTE: see README_DMASON_32_modifications file (in this directory), for some needed DMASON source code changes in HPC environments.
	
	-Build DMASON. 
		mvn -Dmaven.test.skip=true clean package
	-Set the ip (and port if needed) of the master node at /target/resources/systemmanagement/master/conf/config.properties that will be used to connect with the ActiveMQ server. 
		ActiveMQ connection parameters
		activemq.ipmaster = 192.168.12.100
		activemq.portmaster = 61616

	-Create logs/results/ folder in the DMASON target folder
	mkdir target/logs
	mkdir target/logs/results/

2. Generation of initial state files
	-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.data file with agents
		fft.data file with FFT vector
		
	-Move initial state files to DMASON target folder
	mv 0.data ../dmason-master/target/0_1000.data
	mv fft.data ../dmason-master/target/fft.data

3. Start DMASON

	-Master (in the DMASON target directory)
	java -jar DMASON-3.2.jar -m master
	
	-Workers (in the DMASON target directory)
	java -jar DMASON-3.2.jar -m worker -ip 192.168.12.100 -p 61616 -ns 16
		

4. Model compilation

	export CLASSPATH=$CLASSPATH:<.....>/dmason-master/target/DMASON-3.2.jar
	javac it/isislab/dmason/sim/app/DPrisDilemma/*.java
	jar cfv  it/isislab/dmason/sim/app/DPrisDilemma/DPrisDilemma.jar it/isislab/dmason/sim/app/DPrisDilemma/*.class


5. Model execution

	-Open DMASON System Management web site http://127.0.0.1:8080/
	-Follow the guidelines of https://github.com/isislab-unisa/dmason/wiki/System-Management
		
		-To run the Master in a cluster login node. Is better to tunnel access to System Management from local machine browser
			In one terminal:
				ssh -L 8080:127.0.0.1:8080 username@serverloginnode -p 443
				java -jar DMASON-3.2.jar -m master
			In another terminal:
				run workers with SLURM sbatch. Set the IP/port of Master
			Go to 127.0.0.1:8080 with a local browser
		
		-To run the Master in any cluster node, not the login one.
			In one terminal:
				ssh username@serverloginnode -p 443
				srun --nodelist=nodeclustername -N 1 --ntasks-per-node=12 --pty bash
				ssh -N -f -R 8080:localhost:8080 192.168.13.100
				java -jar DMASON-3.2.jar -m master
			In another terminal:
				ssh -L 8080:127.0.0.1:8080 username@serverloginnode -p 443
				run workers with SLURM sbatch. Set the IP/port of Master
			Go to 127.0.0.1:8080 with a local browser

6. Getting results

	-Total time (in the target directori of DMASON install directory)
	cat w1.txt | grep "Total time" | awk '{s+=($7)} END {printf "%f - %d\n", s/NR, NR}'

	-C - num. agents
	cat logs/results/*.txt | grep Double2D | sort | uniq | awk '{s+=($4)} END {printf "%f - %d\n", s/NR, NR}'

	-TOTAL - num agents
	cat logs/results/*.txt | grep Double2D | sort | uniq | awk '{s+=($6)} END {printf "%f - %d\n", s/NR, NR}'

        -To get agents distribution, copy this files to "target" DMASON target directory, go there and run:
        ./PreprocessAgentsDistribution  "logs/results/*.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/>.