N3Sim Project
Quick Start Guide

Overview

The goal of this quick start guide is to give the reader the minimum instructions to install N3Sim (version0.7) and run a simple simulation. Sections Installation, Running N3Sim and Output explain the basic steps to run a simulation. In section Next Step: Automating Simulations, short indications to automate multiple simulations are given. In order to get a deeper knowledge of N3Sim, reading the User Guide is highly recommended.

Contents

Installation

  • The only prerequisite is Java JRE 1.6.
  • Download the jar file N3Sim.jar and the configuration file N3Sim.cfg from here and save them in your N3Sim folder.

Running N3Sim

  • Edit the values of the parameters in the downloaded configuration file (N3Sim.cfg) in order to suit your needs. A list of parameters together with a short explanation of them is available here.
  • Type the following command from the N3Sim folder in your console:

    > java -jar N3Sim-0.7.jar myConfigFile.cfg


    Tip: for heavy simulations it might be a good idea to increase the Java memory to a higher value, such as 1024 MB.

    > java -jar -Xms1024m -Xmx1024m N3Sim-0.7.jar myConfigFile.cfg

  • When the simulation is completed, you just need to check your results (see the next section Output).

Output

Once the simulation has finished, the application will have created a folder under the N3Sim folder with the name specified by the variable outPath in the configuration file. Inside this folder, the following files may be found:

  • A file simulation.txt with the parameters and values used in the simulation.
  • A file receiver_name.csv for each receiver in the simulation. These files have two columns; the first one contains the time steps in nanoseconds, and the second one represents the number of particles measured by the receiver at the corresponding time step.
  • Debugging files info.log (optional) and error.log.
  • Video file graphic.ns1 (optional), to be used with NSVideo.

Next Step: Automating Simulations

  • Read example 1 and/or example 2.
  • Modify your configuration file and build your script.
  • Run the script.
  • Check your results.

Example 1

Let's assume that we want to run several 2-dimensional simulations with particle radius 1, 2, 5 and 10, and we want to repeat each of them 10 times. When using the key word "param" as value for any of the parameters in the configuration file, the program will read its value from the parameters list of the execution command (in the same order that they appear at the configuration file). In this example, we give the value "param" to the variables outPath (so that each simulation has a different folder) and sphereRadius, as shown in Figure 1. Then, a script such as the one shown in Figure 2 will execute all the required simulations automatically.

### N3Sim CONFIG FILE

### SIMULATION PARAMS

outPath=param
graphics=false
infoFile=true
activeCollision=false
BMFactor=1
inertiaFactor=0
time=200000
timeStep=1000

### SPACE PARAMS

boundedSpace=true
constantBGConcentration=false
constantBGConcentrationWidth=0
xSize=2500
ySize=2000
D=1
bgConcentration=10
sphereRadius=param

### EMITTER PARAMS

emitters=1
emitterRadius=100
x=1000
y=500
startTime=1000
endTime=2000
initV=0
punctual=false
concentrationEmitter=false
color=white
emitterType=1
amplitude=1000

### RECEIVER PARAMS

receivers=1
name=rx500
x=1500
y=500
absorb=false
accumulate=false
end=true


Figure 1. Configuration file used to launch simulations with different values of the parameter sphereRadius.


#!/bin/sh

# This script will launch 10 simulations for each value of the PARAM1_LIST.
# Simulations results will be stored in folders named "myTest-i-j", where i
# is the effective value of the PARAM1_LIST for each simulation and j
# is the 1 to 10 repetition for each i.

N=10
PARAM1_LIST=(1 2 5 10)

for (( j = 0 ; j < $N; j++ )); do

for i in ${PARAM1_LIST[@]}; do

java -jar N3Sim.jar myConfigFile.cfg myTest-${i}-${j} $i

done

done

Figure 2. Script to automate simulations for a list of values of a parameter and repeat each simulation 10 times.

Example 2

Let's assume that we want to run several 2-dimensional simulations combining several values for the particle radius (values 1, 2, 5 and 10) with several values for the diffusion coefficient D (0.5, 0.6, 0.7, 0.8 and 0.9). When using the key word "param" as value for any of the parameters in the configuration file, the program will read its value from the parameters list of the execution command (in the same order that they appear at the configuration file). In this example, we give the value "param" to the variables outPath (so that each simulation has a different folder), sphereRadius and D, as shown in Figure 3. Then, the script shown in Figure 4 will execute all the required simulations automatically.

### N3Sim CONFIG FILE

### SIMULATION PARAMS

outPath=param
graphics=false
infoFile=true
activeCollision=false
BMFactor=1
inertiaFactor=0
time=200000
timeStep=1000

### SPACE PARAMS

boundedSpace=true
constantBGConcentration=false
constantBGConcentrationWidth=0
xSize=2500
ySize=2000
D=param
bgConcentration=10
sphereRadius=param

### EMITTER PARAMS

emitters=1
emitterRadius=100
x=1000
y=500
startTime=1000
endTime=2000
initV=0
punctual=false
concentrationEmitter=false
color=white
emitterType=1
amplitude=1000

### RECEIVER PARAMS

receivers=1
name=rx500
x=1500
y=500
absorb=false
accumulate=false
end=true

Figure 3. Configuration file used to launch simulations combining different values of the parameters sphereRadius and D.


#!/bin/sh

# These script will launch simulations combining values of PARAM1_LIST
# with values of PARAM2_LIST.
# Simulations results will be stored in folders named "myTest-i-j"
# where i and j are the values of the parameters.

PARAM1_LIST=(1 2 5 10)
PARAM2_LIST=(0.6 0.7 0.8 0.9)

for i in ${PARAM2_LIST[@]}; do

for j in ${PARAM2_LIST[@]}; do

java -jar N3Sim.jar myConfigFile.cfg myTest-${i}-${j} $i $j

done

done

Figure 4. Script to automate simulations combining a list of values of a parameter with a list of values for another parameter.