MOWE Tandy Simulator - OUWECAD/MOWE GitHub Wiki

####Table of Contents Introduction
Windows Setup
Loading Project Files Into Netbeans
Linux Setup
Coding
Modifying topology.h
Compiling
Uploading to Tandy
Running Code on Tandy
Debugging Code on Tandy
Further Documentation

###Introduction This documentation will guide you through developing, compiling, and running the simulator code for the MOWE hardware modules. I used Netbeans as an IDE for code development and compilation, then used the Tandy supercomputer for compilation, running, and debugging, but if you don’t need an IDE and are more confortable coding directly within a text editor you can develop entirely on Tandy as well. This document assumes that you have a valid account on the Tandy community supercomputer.

###Windows Setup

  1. To setup access to the Tandy supercomputer via Windows, download and install PuTTY. If you already have an SSH client isntalled, you can use that instead.

  2. Configure PuTTY with the following settings: (after configuration, type a name into Sessions->saved sessions and click save to save this PuTTY connection for later use).
    * Host name: tcs.tandysupercomputing.org * Port: 22 * Connection Type: SSH * Under Connection->SSH->X11 check ‘Enable X11 Forwarding’ * Under Window->Selection there is an option to allow righclicking to bring up a Windows-style menu rather than pasting your clipboard into the terminal, which you may want to enable if you primarily use Windows applications.

  3. To setup file transfer to the Tandy supercomputer via Windows, download and install WinSCP. If you already have an SCP client isntalled, you can use that instead.

  4. Configure WinSCP with the following settings:
    * File Protocol: SFTP * Host name: transfer.tcs.tandysupercomputing.org * Port Number: 22 * Username: the Tandy supercomputer username given to you’ * Password: leave blank! For security reasons, you should not save your password here. Instead, type it when prompted while logging on. Once logged on, you can save it for the current session if prompted, so you don't have to enter it for each file transferred for the current session. * Click save, and give your session a name to save these settings for later.

  1. To setup local a local IDE to code and compile, download and install NetBeans. (Optional; You can use your favored IDE instead, or simply code directly on Tandy if you feel comfortable using a basic text editor to write code)
    • NetBeans is a platform-independent IDE, available for Windows, Mac, and Linux, which is why I chose it for this example
    • If using NetBeans, make sure to install the C/C++ module when prompted
  2. To provide a c compiler for Netbeans to use via gcc, download and install Cygwin.
  3. Required packages to add during install are: gcc-core, g++, make, gdb, openmpi - Cygwin should take of all required dependencies when these are selected. (Note: the screenshot below shows search and selection of openmpi packages only, make sure to search for and select all required packages; only these 5 should be required, but feel free to add any additional packages from the Cygwin repository you may find useful)
  4. Add C:\cygwin(64)\bin (or wherever you installed Cygwin) to your Windows path:
    • For Windows 8 go to ‘Edit the System Environment Variables’ in the start menu search box, then System Properties->advanced->environment variables->and add ;C:\cygwin(64)\bin to the end of the value of Path under ‘System Variables’ Make sure to edit the Path entry under 'System variables' and not the one under 'User Variables'
    • For Windows 7 right-click My Computer and go to Properties -> Advanced System Settings link -> Environment Variables button-> and add ;C:\cygwin(64)\bin to the end of the value of Path under ‘System Variables’ Make sure to edit the Path entry under 'System variables' and not the one under 'User Variables'
  5. Restart your computer to apply path changes; this should enable Windows to access Cygwin via commandline from any directory. You can check that this worked by typing “cygcheck –c Cygwin” from a Windows command prompt. To check for module installation, type "gcc --version" "g++ --version" "make --version" and "gdb --version" from the command prompt.
5. Finally, to provide a X server in Windows to use the Tandy debugger, [download](http://sourceforge.net/projects/xming/) and install [Xming](http://sourceforge.net/projects/xming/). The Default install settings should be fine here.

###Loading Project Files Into Netbeans

  1. Unzip the files from hexboard-simulator-setup.zip into your desired loccal working directory.
  2. In Netbeans, go to file -> new project -> C/C++ -> C/C++ project with existing sources. Select your working directory, then click finish to add the project to Netbeans. Netbeans should automatically recognize and import the code and makefile, and run 'make clean' and 'make' to compile the project. If Cygwin and Netbeans are set up correctly, the code should successfully compile.
  3. The only two files within the initial code that you should need to edit are comm_state_test.c and topology.h comm_state_test.c is the simulation file itself, and topology.h describes the physical hardware setup and connections of the network you want to simulate. Other files within hexboard-simulator-setup are primarily concerned with the simulation back-end, allowing comm_state_test hardware modules to interface properly with each other, and allowing the simulation to properly multithread itself and run on Tandy. These should not need to be edited, but are required for the simulation to compile and run.

###Linux Setup

  1. Any IDE that supports gcc and OpenMPI should work fine. Make sure to install and setup these two packages, as well as g++ gdb and make. Eclipse and Netbeans were both able to compile the simulation in a virtual machine. You can run version checks from the command line to ensure correct installation, similar to the Windows checks above. Your package manager should be able to pull all of these. If OpenMPI is not available on your favored distribution, you may have to build it yourself from source
  2. You will also need to be able to SSH and SFTP into the Tandy supercomputer to run and debug the simulation, so install appropriate clients.
  3. If you build your own version of OpenMPI from source and modify the configuration so that you are able to run multiple OpenMPI threads on a single core, you may be able to run the simulation locally. That is beyond the scope of this documentation, however, which is focused on running the simulation on the Tandy supercomputer.

###Coding

  1. There should only be two files in the project that you should have to edit:
  • topology.h contains the physical setup and hardware connections of the MOWE network you want to simulate, including the number and of physical modules, and which modules they are connected to.
  • comm_state_test.c contains the actual simulation code. This currently is an incomplete state-machine simulation. You can either add in your own state for the simulator to enter into after the existing code, or modify it to suit your needs.
  • These can be edited in Netbeans by doubleclicking clicking the appropriate file under the project tab once the source has been imported into Netbeans as a project.
  1. If you want to code directly on Tandy, instead of Netbeans or another locally installed IDE, the Tandy ssh interface supports vim, emacs and nano. Navigate to your working directory and use ‘emacs comm_state_test.c’ to edit.

###Modifying topology.h

  1. Please see the MOWE-Automatic-Topology-Generator wiki documentation for more information on generating a topology.h file for the network you wish to simulate. Once you have the desired topology.h file, you can place it in your local working Netbeans directory, and upload it to your Tandy directory.
  2. Sample topology.h files for fully connected tiny (7 node), small (19 node), medium (37 node), and large (127 node) networks are available for testing. These files were generated using the topogen.m matlab script.
  3. topogen.m generates two types oftopology files; those intended for the physical MOWE module firmware, and those intended for use in the Tandy simulator. The two files are not interchangable, so make sure you generate the correct file for your intended use.

###Compiling

  1. For Netbeans, simply rightclick the toplevel project in the projects window in the top-left of the screen and select ‘clean and build’. This will run the ‘make clean’ and ‘make’ lines from the project’s Makefile. The output window should show any coding errors, or signal a successful compile. Make sure to delete any .exe files compiled during this process before uploading the project to Tandy, as these will not run in that environment and may interfere with compiling on Tandy. (they probably won't run in Windows either, unless you built your own functional OpenMPI from source)
  2. To compile code on Tandy, SSH and login, then navigate to the project’s working directory. Delete any .exe files you find, these are made by Windows compilers and are not needed. You will need to load the required modules, then run the makefile with the following commands:
  • module load gcc
  • module load openmpi
  • make clean
  • make
  1. If, for some reason, your project compiles locally, but not on Tandy, you can edit comm_state_test.c directly on Tandy via emacs, vim, or nano, then try to recompile.

###Uploading to Tandy

  1. Uploading to Tandy via Windows is accomplished via WinSCP, which should already be installed and configured. Setup of WinSCP is discussed above. WinSCP should provide a familiar graphical FTP interface for managing the files in your Tandy home directory.
  2. Log in and drag your working directory from your local computer (hexboard-simulator-setup by default) on the left to your Tandy home directory (or working directory) on the right. If you are only updating simulation files, you may only need to copy topology.h and comm_state_test.c
  3. Uploading to Tandy via linux may be done via scp in a terminal.

###Running Code on Tandy

  1. If you are simulating a small network (<10 nodes, and under 1 minute compile/run time), it’s probably okay to just run it on Tandy (after compiling) from within the login node via your ssh terminal.
  • To run your code, navigate to your working directory on Tandy and use the commands:
    i. module load gcc
    ii. module load openmpi
    iii. mpirun -n 4 ./comm_state_test
    iv. replace '-n 4' with '-n X' where X is the total number of simulated boards in the network, as specified by topology.h
  • To output the results to a file (testoutput.txt for example), instead of having them display directly within the terminal session, use the command mpirun -n 4 ./comm_state_test > testoutput.txt
    i. The current simulation code will not cleanly exit itself when outputting results to a file within a terminal session, so press ctrl-c after you feel the simulation is complete to return to a command prompt.
  1. Any more complex job requiring either a longer runtime (over 30 seconds) or a large number of simulated network modules should be submitted to the supercomputer using the bsub system, as the login node is not intended to run complex simulations. A sample bsub file is included within the hexboard-simulator-startup files. This will need to be modified as needed to submit your job.
  • For the line “mpirun -n 4 ./comm_state_test” change 4 to however many boards you are simulating.
  • Find the line #BSUB -J "job_name" and replace job_name with whatever you want to name your job. Delete this line if it doesn’t need a name.
  • Find the line #BSUB -u [email protected] and change to your email address to have the computer send you an email when your job starts and ends. Delete the three lines #BSUB –B #BSUB –N and #BSUB -u [email protected] if you do not need email notification.
  • Change #BSUB -q short to #BSUB -q long if your job will take more than 30 minutes
  • Change #BSUB -n 4 to #BSUB -n X where X is the number of simulated hardware boards in the network.
  • #BSUB -o stdout.%J tells the system to save the output from your job into the file stdout.J where J is the task number or job name assigned by the system. Change stdout.%J to your desired output name.
  • #BSUB -e stderr.%J tells the system to save any errors generated by your job into the file stderr.J where J is the task number or job name assigned by the system. Change stderr.%J to your desired errorfile output name.
  • Change mpirun -n 4 ./comm_state_test to mpirun -n X ./comm_state_test where X is the number of simulated hardware boards in the network, and comm_state_test is the name of the compiled simulation file.
  • Once submit.bsub has been edited, you can submit the job to Tandy with the command i. Bsub < submit.bsub
    ii. This will submit your job and give it an ID number.
    iii. The status of your submitted jobs can be viewed using “bjobs”
    iv. To remove a scheduled job use “bkill ”
  • Submit essentially acts as a batch script, sending information about a job request, followed by the required commands, to the batch submission queue of the Tandy supercomputer. Any lines prefaced with #BSUB are submission configuration commands, while the remaining lines are the commands you are requesting Tandy to run. The lines at the end of the submit.bsub file may thus be edited as required to run any other files you need, or load additional required modules. For more information on submit.bsub configuration, please see the Tandy help documentation. The instructions referring to -n in the Tandy documentation do not apply to this simulation, as we are running multiple threads per core, corresponding to the number of simulated boards, rather than the more typical 1-thread-per-core over n cores job that Tandy usually runs.

###Debugging Code on Tandy

  1. For catching memory leaks, buffer overflows, and coding inefficiencies, valgrind may be used as a mpirun option. Note that valgrind may provide considerable output, and you may want to save this into a text file for later examination. For example (after loading gcc and mpi modules):
  • mpirun –n 4 valgrind ./comm_state_test (runs comm_state_test on the local node with 4 boards using valgrind)
  • mpirun –n 4 valgrind ./comm_state_test > output.txt (runs comm_state_test on the local node with 4 boards using valgrind and saves the output to output.txt)
2. A parallel debugger (Forge) is also available on Tandy for debugging simulation code running across multiple threads (multiple simulated boards). Please ask Asaad for the directory location of this debugger if you need to access it. * You will need [X11 Forwarding](#windows-setup) enabled in PuTTY to use Forge (the parallel debugger). If you are followed the windows setup setups above, this should already be enabled. * Before running the debugger through PuTTY, you will need a running X windows server, such as Xming (installed [earlier](#windows-setup)). When using Forge, start Xming (start->programs->Xming->Xming) before you begin your PuTTY session.

###Further Documentation
NetBeans Documentation - Contains information regarding NetBeans C setup - most of this was already covered here.
Using the Tandy Supercomputer - most of this has been covered above, but this might be a useful reference if you need to run on multiple nodes or see what libraries are available on Tandy.

⚠️ **GitHub.com Fallback** ⚠️