N3Sim Project
Quick Start Guide

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.

• Installation.
• Running N3Sim.
• Output.
• Next Step: Automating Simulations
• Example 1
• Example 2

• 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.

• 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).

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.

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

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.

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

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

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.

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

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