NFsim is useful if you want to simulate a system with many interacting molecules in different states and/or molecules with many interacting sites where a bond can be formed. For an in depth explanation about how NFsim works, we refer to the first chapter of the NFsim manual provided by Yale University, which can be found here:
NFsim_manual_v1_11.pdf
If you prefer to read a pdf booklet, you can donwload it here.
The second chapter "Getting Started" shows different steps which will guide you to install the required software. It is, however, more focused on Mac and Linux, we will therefore provide additional information for windows users.Furthermore, there are also some links in the manuals that are expired, so we will also be providing working links in this tool.
The first step is to download the NFsim zip file, which can be found on this page (instead of the provided site in the manual).
In most cases, the zip file will be saved on the folder "Downloads, which is undesired. We recommend that you place the file to another location, which can easily be found and reached. For example, we created a new folder on our D-drive (mostly used for data), and named it NFsim. We placed the zip file into this folder and there we unpacked / unzipped the file. NFsim is now located in D:NFsim\NFsim_v1/11. It is recommended to use names without spaces, or choose an underscore _ instead.
In addition to downloading NFsim, it is required to install a Perl interpreter for Windows user. We downloaded Active Perl (name: ActivePerl-5.24.1.2402-MSWin32-x64-401627.exe) from here.
The last download we also recommend is that of an text editor, namely Notepad ++, which can be found here.
This was additional information for step 1 of chapter 2.
The next step in the manual explains how you can open a terminal / command prompt. Windows uses the name CMD. This Command Prompt can be find by going to "start" and then by typing "cmd. After opening cmd, you should check if perl is installed correctly by typing: "perl -v". The results are shown in Figure 1.
Figure 1: Command Prompt
The next step is to check whether NFsim is also installed correctly. This is done by first changing the directory of the command prompt to the directory were NFsim is installed / unzipped. We already mentioned that we installed it on our D-drive, so the first step is to change the drive. The easiest way to do this is by typing: "D:", which lets you go the D-drive after you use the "enter" key on your keyboard. Next, change the directory to the NFsim directory. This can be done with: "cd D:\NFsim\NFsim_v1.11" where cd stands for Change Directory and after a space you type the folders where NFsim is installed. This path can be found easily by using the windows explorer, going to the correct folder and then clicking on it. The path then changes from the one in Figure 2 to a selectable name, like "D:\NFsim\NFsim_v1.11", which can be copied and then placed in the command prompt. The shortcut "ctrl + v" does not work in the command prompt, so you will need the right mouse button and paste the text.
Figure 2: Select Path with Windows Explorer
The next step is to verify that the installation of NFsim was successful, which can be done by typing: "perl BNG2.pl -v". If the installation is correct, the command prompt will look like the command prompt in Figure 3, after pressing the "enter" key.
Figure 3: Change directory of the command prompt
Together with the installation of NFsim, you installed also some example models, which can be found in the folder "models". The simple_system.bngl file is very nice as a start to see how output can be generated. We recommend that you open the bngl files with Notepad ++, as this is a very easy way to not only look at the files, but also to edit them if desired.
Next to the simple_system.bngl file, we wrote a general file of our own with nice descriptions of each step and called this file: "system_example.bngl". The description about how a bngl file is build up, can be found on our wiki page in the rule-based-model section and can be found here.
Link to download the bngl file.
(You need to save this file in the "models" folder of "NFsim_v1.11" and change .txt to .bngl)
After you wrote your own bngl file, it is time to execute the file and get some results. The easiest way is to have a bngl file which has a line that states: "writeXML();" so that an XML file will be created during the first time we run the model and we can use the xml-file to run the same model again, but with different time steps.
The xml-file is created by typing the following line in the command prompt, as shown in Figure 4:
"perl BNG2.pl -xml models/system_example.bngl"
Figure 4: Command Prompt when running example via perl
After generating an xml-file, you can run the model in another way, namely via a windows executable. The advantage is that you then can give additional commands, like the command "dump". NFsim calls this a flag and they made a whole table that describes the command line arguments and their function. The table can be found on pages 38-40 of the manual.
For the dump flag, we first need to make an empty folder. This can be done easily with the command "mkdir" followed by the name of the folder you want to create, for example "dumpDir_example_dump". Furthermore, with -Steps you can redefine the number of steps, with -sim you can define the end time of the simulation and with -o, you can specify the output file of your simulation. The command line can for example look like below and in Figure 5:
.\bin\NFsim_MSWin32.exe -xml system_example.xml -dump "[0:0.1:1]->dumpDir_example_dump/" -oSteps 10 -sim 1 -o "system_example_nf.gdat"
Figure 5: Command Prompt when running example via windows executor
Codes for visualization
It is easy to visualize the results generated with Matlab. NFsim also provides some tools that you can use in the folder NFtools, but we will explain how you need to prepare Matlab and how you can use them. We ourselves already had Matlab 2016b installed, so the visualization may differ a bit, depending on your matlab version. There are also some functions that have changed over the time that Matlab exists, so it is possible that you will get a warning if you use another version. In most cases it is not a problem.
After opening Matlab you will end up in the home tab, shown in Figure 6. In this tab you can find an icon with the description: "Set Path", like in Figure 7.
Figure 6: Home Tab of Matlab
Figure 7: Matlab Set Path icon
The window "Set Path" then opens and by clicking on "Add with Subfolders…" you can select the NFtools folder. This is done by first going to the driver (D-drive), followed by the NFsim folder, then NFsim_v1.11 and there you will see the folder NFtools, as in Figure 8. Select the NFtools folder, press Save and then Matlab will add the folders and their subfolders.
Figure 8: Select the folder NFtools in Matlab
Then you need to go to the right directory for the Matlab editor. In Figure 9 you need to search for the icon visualized in Figure 10, which stands for "Browse for folder". Then select the right path, which in this case, again is to "NFsim_v1.11". The matlab code you can download below, can be saved in the general NFsim folder, which you can see in the editor window as depicted in Figure 9.
Figure 9: Editor Tab Matlab
Figure 10: Matlab Change Directory icon
By clicking on the green arrow which says "run", Matlab will execute the program and give output in the command window, see Figure 11, but also four figures with graphs. The first figure contains three different graphs, which are also displayed separately in the other three figures. We also gave Matlab the command to save the last three figures, so that you can easily access them again and place them on your wiki page for example. The figures generated with Matlab for the system_example file (with an end time of 10 seconds with 100 steps) are depicted in Figures 12-14.
Figure 11: Matlab Command Window
Figure 12: Figure a, showing the amount of molecules over time
Figure 13: Figure b, showing the total amount of complexes over time
Figure 14: Figure c, showing the average complex size time
If you look at the legends, you see that we used different methods to generate the graphs in the figures. Which method is most useful depends on the system that is implemented in the model. Therefore, it is useful to look at the data in the workspace (Figure 15) of Matlab to see which method works the best for generating your output. In our example, the results of method 1 and method 2 are the same for the total amount of complexes and for the total amount of molecules, so therefore we choose to only depict the results of method 1 and 3 in our graphs.
