1DT116_Assignment

Assignment of 1DT116 Low-level Parallel Programming at Uppsala University

What this simulation is

Pedestrian simulation is the study of the movement of people through various environments in order to understand the collective behaviour of crowds in different situations. Accurate simulations could be useful when designing airports or other public spaces, for understanding crowd behaviour departing sporting events or festivals, and for dealing with emergencies related to such situations. Understanding crowd behaviour in normal and abnormal situations helps improve the design of the public spaces for both efficiency of movement and safety, answering questions such as where the (emergency) exits should be put.

This system simulates an area of people walking around. Each person, or agent, is moving towards a circular sequence of waypoints, in the 2D area. The starting locations and waypoints are specified in a scenario configuration file, which is loaded at the beginning of the program run.

What this simulation can mainly do

1. Each dot in the simulation represents a person. When people move to the next position, several people will be guarantee to not acquire the same coordinate (position), which simulates the real-world scenario that two people cannot stand on the same position (except that one person stands on the head of another person, which is unlikely).
2. The region is separated into several subregions, which is hardcodely fixed to be 16 subregions. Each subregion will receive its own thread to move its people in its subregion. As a result, several people in several subregions can move to the next position simultaneously because of multithreading programming using OpenMP. When a person want to move from one to another subregion, it can be done without a race condition.
3. The heatmap generation, visualizing the intensity of people in a particular area, is done simultaneously on GPU using CUDA with the collision detection and people movement in step 1, which is done on CPU. However, this simulation guarantees that both tasks are done before continuing to the next step of simulation.

This simulation is available through the command demo/demo --export-trace --omp <scenario's XML file>.

What this simulation can also do

With --simd flag, four people can move to the next position simultaneously because a vectorization method is applied using Intel Intrinsic. The x and y coordinate is stored separately in two different arrays so that the vectorization can be implemented. In other words, the coordinate is realigned from Array of Structure (AoS) to Structure of Array (SoA).

However, this version does not include the collision detection yet. Therefore, several people can acquire the same coordinate, which is an undesired behavior. This is a further improvement for this project!

Contributor

Alexander Verdieck is also a co-contributor with this code.

Preparing to run on your machine

(Jump over to the building section if you will be using the machine that we provided)

We will provide instructions to run the codebase on an Ubuntu system. If you use Windows, you should be able to use WSL2 to achieve the same goal.

Prerequisite: Qt5 (optional)

If you would rather not use qt-mode and instead only use the export-trace mode, then you can skip this step. The configure step will take care of this.

Qt5 is optionally required to build and run the assignment using qt-mode. Tested with Qt5 on Ubuntu 24.04.1. Installed Qt5 with the following command: (You'll probably need to run with sudo)

# apt install qtbase5-dev

If you cannot install Qt5, but you do have Qt4 then you will need to modify the include and library arguments in demo/Makefile. Change the qt5 strings under QTINCLUDES and LIBS to your Qt version.

Prerequisite: TinyXML-2

The configuration files of this project are specified in XML. We rely on the TinyXML2 library to read in the configuration files. If you are on Ubuntu, the following command should install the library for you.

# apt install libtinyxml2-dev

Prerequisite: CUDA

The 2nd (optional) and 4th part of the assignment requires running the code using CUDA. This also means that you need to have a Nvidia GPU that is capable of running CUDA.

If this is the case, please go ahead to the CUDA Installation Guide for Linux and download and install the CUDA toolkit and the CUDA drivers. I used the Network Repo Installation for Ubuntu approach then followed the common installation instructions (next section that follows). Be sure to read and follow the pre-installation steps.

Make sure to add the CUDA bin directory to the PATH.

I added the following line to a new file called /etc/profile.d/cuda.sh (need to use sudo to make this file. Note that your binaries may be located in a different directory).

export PATH=$PATH:/usr/local/cuda/bin

Also, you need to change the permission of the file.

sudo chmod 0644 /etc/profile.d/cuda.sh

Try running any of the following commands to check if CUDA is setup properly.

$ nvidia-smi # This command should list your GPU
$ nvcc --version # This command should print the version of your cuda compiler

You could also check the post-installation steps, which include more detailed instructions on setting the PATH, and try verifying whether our install was successful by running some sample code.

Configure your machine

Whether you are working on MacOS or on Ubuntu, if you have CUDA and/or QT installed on your Ubuntu machine, the makefile will need to slightly differ.

The provided configure.sh file should take care of this for you. If you are not using Ubuntu, you may need to slightly modify the is_ubuntu() function in the script to allow your system to be recognized. (Ask ChatGPT for help).

$ ./configure.sh

This step is required whenever you first clone your repository. (Or if you install the CUDA framework, or the QT5 framework, you'll need to configure again.)

Building

Now once you have setup your machine OR you are running on our provided machine, you can start building and running the project.

$ make

This should build both binaries in libpedsim then in demo

If you are using your own machine

If during the build the compiler complains of unknown path to the Qt headers (include path), check the path in QTINCLUDES and make sure they exist on your system. Your system may put the include files at a different location. The makefile currently tries to locate the Qt header files using the following command:

$ qmake -query QT_INSTALL_HEADERS

If this fails, try to locate the header files using the following command:

$ find / -name QTHEADER.h` (where the QTHEADER.h the compiler is looking for)

Using the results fix the path in QT_HEADERS variable in the demo/Makefile

If working with Ubuntu and you use the command above to install QT, this shouldn't be an issue... (Let us know if it is.)

Running

If the build is successful, run the simulator using the following command

$ demo/demo scenario.xml

If you get an error about not finding any display, then you need to connect to the provides server with an X session.

On Mac/Linux, on your terminal, add the -Y argument in your ssh command. On Windows, start your X-server application (e.g. Xming), and configure enabling X11 in your PuTTY configuration.

How to continue

# Now, you should in the folder "/mnt/d/.../llpp/1DT116_Assignment"
cd demo
./demo --export-trace ../scenario.xml

or

demo/demo --export-trace --seq scenario.xml
demo/demo --export-trace --omp scenario_box_2.xml
demo/demo --export-trace --seq hugeScenario.xml
demo/demo --timing-mode --omp scenario.xml
demo/demo --timing-mode --omp scenario_box_2.xml
demo/demo --timing-mode -- omp hugeScenario.xml
demo/demo --max-steps=10000 --timing-mode hugeScenario.xml
OMP_NUM_THREADS=8 demo/demo --timing-mode --max-steps=10000 hugeScenario.xml
OMP_NUM_THREADS=16 demo/demo --timing-mode --omp --max-steps=1500 hugeScenario.xml

-------------------------------------------------------

cd ../visualizer
source venv/bin/activate
pip install -r requirements.txt

then run

python visualize_export.py ../demo/export_trace.bin
or
python visualize_export.py ../export_trace.bin

depending on where you are in the terminal.

If visualize_export.py:235: UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure. plt.show() is shown, pip install pyqt5. Then run python visualize_export.py ../demo/export_trace.bin again.

After updating the implementation (such as editing ped_model.cpp)

• run make in the most outer folder (/mnt/d/.../llpp/1DT116_Assignment)
• follow the section How to continue above
• No export_trace.bin will be created from using --timing-mode